React Styleguide Generator (Alt!)
- Use the
2.x
versions for babel 5,3.x
for babel 6.' - PRs are welcome, feel free to contribute to the project!
A React component guide that generates code examples, prop documentation, rendered component samples and is built for active development.
- Renders out components that can be interacted with
- Uses
webpack
+ hot module replacement to automatically update the guide as you work on your components react-docgen
is used under the hood to document your component'spropTypes
- Can manually + automatically generate code samples w/ syntax highlighting
Demo using the React-Bootstrap.
Fork notice
This project is originally forked from react-styleguide-generator.
Differences:
- Removed
browserify
and replaced withwebpack
+ hot module replacement - Complete overhaul of the core
rsg.js
lib to supportwebpack
react-docgen
generation and asset distribution moved to custom webpack plugins- Fixed a bug where using input text boxes and typing into them will shift focus to the search box
- Improved highlighting performance - extremely large guides should not take forever to render
- Config file can now be an exported object, allowing for more dynamic configuration
See HISTORY.md
for future update info
Prereqs
- React 0.14.x. Install both
react
andreact-dom
. - Was developed on node 4, but has been known to work on ~0.10.45.
Installation
npm install rsg-alt
Documenting your React components
Create file for the styleguide, and then add some documentation to a static field named styleguide
. You can use the ES6 syntax by Babel.
Componentstatic styleguide =index: '1.1'category: 'Elements'title: 'Button'description: 'You can use **Markdown** within this `description` field.'code: `<Button size='small|large' onClick={Function}>Cool Button</Button>`className: 'apply the css class'props:size: 'large'{}{return<Button size='large' onClick=thisonClick>Cool Button</Button>}
index
: Reference to the element's position in the styleguide (optional)category
: Components category nametitle
: Components titledescription
: Components description (optional)code
: Code example (optional). Not specifying this will not auto-generate an example.className
: CSS class name (optional)props
: Properties to assign to the rendered example component (optional)
Demo
Additional examples in tabs (optional)You can optionally use tabs to segment out examples for a component:
Componentstatic styleguide =…// Component to use for generating additional examplesexampleComponent: Button// Options for the first tabdefaultTabOpts:firstTabName: 'Default example'// Array of additional example tabsexamples:tabTitle: 'Default'props:children: 'Default'tabTitle: 'Primary'props:kind: 'primary'children: 'Primary'{}
exampleComponent
:ReactElement
to use to generate the examples.examples
: Array of examples, which generates additional tabs of example components and sample codeexamples[].tabTitle
: Title of example tabexamples[].props
: Properties to assign to the rendered example componentexamples[].props.children
: (optional) Child elements to assign to the example componentexamples[].code
: (optional) Code example. Omitting this will attempt to auto-generate a code example using theexamples[].props
Demo
Additional examples via doc comment (optional)Doc comment support example is:
/*** Substitute this description for `styleguide.description`.*/// required for prop documentationstatic displayName = 'ExampleButton'static styleguide =…// Document the props via react-docgenstatic propTypes =/*** Block level*/block: ReactPropTypesbool/*** Style types*/kind: ReactPropTypes{return <Button block kind='primary'>Cool Button</Button>}
If necessary, visit react-styleguide-generator-alt/example to see more complete examples for the documenting syntax.
Generating the documentation
Command line tool
A common usage example is below.
# The default output to `styleguide` directoryrsg 'example/**/*.js'
Type rsg -h
or rsg --help
to get all the available options.
Usage: rsg [input] [options]
Options:
-o, --output Output directory ['styleguide']
-t, --title Used as a page title ['Style Guide']
-r, --root Set the root path ['.']
-f, --files Inject references to files ['']
-c, --config Use a js/json config file ['styleguide.json']
-p, --pushstate Enable HTML5 pushState [false]
-v, --verbose Verbose output [false]
-d, --dev Start server with webpack hmr [3000]
Examples:
rsg 'example/**/*.js' -t 'Great Style Guide' -f 'a.css, a.js' -v
# Necessary to use a config file if you want to enable react-docgen
rsg 'example/**/*.js' -c 'styleguide.json' -v
# Example 2 - config file does module.exports = { ... }
rsg 'example/**/*.js' -c 'styleguide.js' -v
Gulp
var gulp =var RSG =gulp
Grunt
var RSG =grunt
API
RSG(input, [options])
Returns a new RSG instance.
input
Type: String
Refers to glob syntax or it can be a direct file path.
options
output
Type: String
Default: 'styleguide'
Output directory path.
title
Type: String
Default: 'Style Guide'
Used as a page title and in the page header.
reactDocgen.files
Type: Array
Default: input
An array of glob
-able file/paths for react-docgen
to parse. If not specified, will default the value to input
.
root
Type: String
Default: '.'
Set the root path. For example, if the styleguide is hosted at http://example.com/styleguide
the options.root
should be styleguide
.
files
Type: Array
Default: null
Inject references to files. A usage example is:
files:'//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css''a.css''a.js''icon.svg'
Check for the existence of the files and only copy the files if it exists.
styleguide/files
├─ a.css
├─ a.js
└─ icon.svg
Inject file references into index.html if the files with the extension .css
or .js
.
……
config
Type: String|Object
Default: styleguide.json
The entire range of RSG API options is allowed. Usage example.
- An object can be passed instead of a filename that contains the RSG API options.
- A Javascript file can be passed in that exports an object instead:
// styleguide.jsmoduleexports = "title": "React Style Guide" "files": "//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css" "example/example.css" "webpackConfig": {}
pushstate
Type: String
Default: false
Enable HTML5 pushState. When this option is enabled, styleguide will use history API.
webpackConfig
Type: Object
Default: {}
Uses deepmerge
to merge in a custom webpack configuation to the rsg webpack configuration. Existing arrays (eg plugins) are appended to maintain functionality.
transpileIncludes
Type: Array<String|RegExp>
Default: null
Adds a custom rule(s) to the webpack loader to include additional items to transpile via babel-loader
. This is provided as a convenience to using webpackConfig
directly.
babelPlugins
Type: Array<String>
Default: null
Add Babel plugins in addition to those automatically provided with the presets react
, es2015
, stage-0
. EG: You might want to support decorators with transform-decorators-legacy
.
rsg.generate([callback])
Generate the files and their dependencies into a styleguide output.
Demo
Get the demo running locally:
git clone git@github.com:theogravity/react-styleguide-generator-alt.gitcd react-styleguide-generator-alt/example/npm installnpm start
Visit http://localhost:3000/ in your browser.
styleguide
static for production
Remove the It is most likely that you will not have use for the styleguide
static when you're using your component in production. To remove the static (and other unnecessary statics) during transpiling, use babel-plugin-transform-react-remove-statics
Troubleshooting
Error: No suitable component definition found.
Make sure your component contains displayName
and render()
.