React Styleguide Generator
Easily generate a good-looking styleguide by adding some documentation to your React project.
Demo using the React-Bootstrap.
Installation
npm install react-styleguide-generator
Which requires React 15.x.x or newer. To install it npm install react
.
Quick Start
NOTE: By default Babel's static
keyword is disabled. You can turn them on individually by passing stage 0
as a babelrc or options.babelConfig.
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'{}{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)
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// 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/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 the config file ['styleguide.json']
-p, --pushstate Enable HTML5 pushState [false]
-v, --verbose Verbose output [false]
-w, --watch Watch mode using `browserifyConfig`
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
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.
pushstate
Type: String
Default: false
Enable HTML5 pushState. When this option is enabled, styleguide will use history API.
babelConfig
Type: Object
Default: null
A usage example is below. See the babel docs for the complete list.
babelConfig:stage: 0
browserifyConfig
Type: Object
Default: { standalone: 'Contents', debug: true }
A usage example is below. See the browserify docs for the complete list.
extensions: '' '.js' '.jsx'
watch
Type: String
Default: false
Enables watchify
for when the input
files change, speeding up rebuild time.
rsg.generate([callback])
Generate the files and their dependencies into a styleguide output.
Demo
Get the demo running locally:
git clone git@github.com:pocotan001/react-styleguide-generator.gitcd react-styleguide-generator/example/npm installnpm start
Visit http://localhost:3000/ in your browser.
Troubleshooting
Error: No suitable component definition found.
Make sure your component contains displayName
and render()
.