React Styleguide Generator

Easily generate a good-looking styleguide by adding some documentation to your React project.

Installation

npm install react-styleguide-generator

Which requires React 0.13.0 or newer. To install it npm install react.

Quick Start

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.

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.

import React from 'react'
import Button from './Button'

export default class extends React.Component {
  static 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'
  }

  onClick () {
    alert('Alo!')
  }

  render () {
    return (
      <Button size='large' onClick={this.onClick}>Cool Button</Button>
    )
  }
}

index: Reference to the element's position in the styleguide (optional)
category: Components category name
title: Components title
description: Components description (optional)
code: Code examples (optional)
className: CSS class name (optional)

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` directory
rsg '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]

Examples:
  rsg 'example/**/*.js' -t 'Great Style Guide' -f 'a.css, a.js'

Gulp

var gulp = require('gulp')
var RSG = require('react-styleguide-generator')

gulp.task('styleguide', function (done) {
  var rsg = RSG('example/**/*.js', {
    output: 'path/to/dir',
    files: ['a.css', 'a.js']
  })

  rsg.generate(function (err) {
    if (err) {
      console.error(String(err))
    }

    done()
  })
})

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.

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.

<!doctype html>
<html>
  <head>
    …
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css">
    <link rel="stylesheet" href="files/a.css">
  </head>
  <body>
    …
    <script src="files/a.js"></script>
  </body>
</html>

config

Type: String
Default: styleguide.json

The entire range of RSG API options is allowed. Usage example.

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']
}

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.git
cd react-styleguide-generator/example/
npm install
npm start

Visit http://localhost:3000/ in your browser.

alkhe / react-styleguide-generator