Documentation generator for collections of react components.
JavaScript CSS HTML
Latest commit 1221716 Oct 4, 2016 @ryan-roemer ryan-roemer * Replace `concurrently` with [`builder concurrent`](https://formidab…
… for more powerful + flexible `npm` script execution.

* Remove dependencies on `concurrently` is not actually used for `npm` scripts.
* Upgrade `builder` dependencies if already existing.
* Sort `dependencies` + `devDependencies` by key.

> This PR has been automatically opened by your friendly [`multibot`]( The transform code and documentation is available at:

Travis Status



Ecology allows you to write markdown documentation for React components that includes interactive playground sections and auto-generated propType specifications.

See the demo app for a complete example:

# Runs the demo component documentation dev-server
# and open it in your default browser.

$ npm run dev && npm run open-demo

Component PropType Documentation

  1. Your component should be created using React.createClass() or class Foo extends React.Component.
  2. Your component should define propTypes in the createClass object literal or as a static property of the class.
  3. Your component may define default props as getDefaultProps method (React.createClass() syntax), or as a defaultProps static property of the class.
  4. You should add a JSDoc-style comment block for each prop, with a description and optional @examples.

    // createClass() example
    const MyComponent = React.createClass({
      propTypes: {
         * A test prop
         * @examples "Test", "More Test", "Yep"
        testProp: React.PropTypes.string
      render() {
        return <div>Sample</div>;
    // class declaration example
    // NOTE: Requires `babel-preset-stage-1`
    class MyComponent extends React.Component {
      static propTypes = {
         * A test prop
         * @examples "Test", "More Test", "Yep"
        testProp: React.PropTypes.string
      render() {
        return <div>Sample</div>;

Writing Your Component Documentation

Create these files according to the below examples:

  • docs/docs.jsx
  • docs/
  • docs/index.html
  • docs/webpack.config.js

  1. Create docs/docs.jsx

    // docs.jsx
    import React from "react";
    import ReactDOM from "react-dom";
    import Ecology from "ecology";
    import * as docgen from "react-docgen";
    import MyComponent from "../src/my-component";
    class Docs extends React.Component {
      render() {
        return (
          <div className="demo">
              // This loads up your markdown documentation.
              // This loads up your component source so Ecology can inject the `propType` table.
              // The `scope` prop is used by Component Playground to render live code snippets.
              // It needs React, ReactDOM, and your component.
              // See
              scope={{ React, ReactDOM, MyComponent }}
    ReactDOM.render(<Docs/>, document.getElementById("content"));
  2. Create docs/

    Interactive Docs for My Component
    A `playground` triple-backtick snippet will render your component for you. This is useful for quick interactive component demos without the need to add boilerplate.
    <MyComponent />
    NoRender Playground
    A `playground_norender` triple-backtick snippet will not do automatic rendering of your component; you have to manually call `ReactDom.render`. Useful for examples of using your component in context.
    var App = React.createClass({
      render() {
          return (
          <MyComponent />
    ReactDOM.render(<App/>, mountNode);
    ## Prop Types
    Ecology will inject a `propTypes` table at the bottom of your component docs. This is generated from the component `propTypes` definition, and takes into account JSDoc style comments for each `propType`
  3. Create docs/index.html

    // index.html
    // Minimal example. See `demo/index.html` for an example with fallbacks for older browsers.
    <!doctype html>
        <title>Ecology Demo</title>
        <link rel="stylesheet" href="//"/>
        <link rel="stylesheet" href="//"/>
        <div id="content"></div>
        <script type="text/javascript" src="//"></script>
        <script type="text/javascript" src="//"></script>
        <script type="text/javascript" src="main.js"></script>
  4. Create docs/webpack.config.js

    // webpack.config.js
    module.exports = {
      devServer: {
        contentBase: __dirname,
        noInfo: false
      output: {
        path: __dirname,
        filename: "main.js",
        publicPath: "/"
      devtool: "source-map",
      entry: {
        app: ["./docs/docs.jsx"]
      resolve: {
        extensions: ["", ".js", ".jsx"]
      module: {
        loaders: [
            test: /\.jsx?$/,
            loader: "babel-loader",
            query: {
              presets: ["es2015", "react"]
            exclude: /node_modules/
  5. Install dependencies and run webpack-dev-server

    $ npm install -S babel babel-core babel-preset-es2015 babel-preset-react babel-loader raw-loader ecology react react-dom react-docgen webpack webpack-dev-server
    $ node_modules/.bin/webpack-dev-server --port 3000 --config docs/webpack.config.js --watch --content-base docs

Required Props

  • Overview - Markdown documentation file in raw/string format
  • Source - React class source file in parsed react-docgen format
  • Scope - Scope for component-playground components. Used by Component Playground to render live code snippets. It needs React, ReactDOM, and your component.

Optional Props

  • customRenderers - Pass an object with custom marked renderer methods. ex link: function(href, title, text) {return href}. A list of available elements is available here. Note: Method must return a string.
  • exportGist - Adds a button to export the playground source as an anonymous Gist on Github. Enabling this adds a Toolbar component to the markup, with a Button-GistExport component and Toolbar-Message area for displaying error messages.
  • copyToClipboard - Adds a button to copy the playground source to the clipboard. Enabling this adds a Toolbar component to the markup, with a Button-Clipboard component.

Deploying Your Docs

Help us write this documentation!