1.7.0 • Public • Published

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 `propTypetable.
          // The `scopeprop is used by Component Playground to render live code snippets.
          // It needs ReactReactDOMand your component.
          // See
          scope={{ React, ReactDOM, MyComponent }}
ReactDOM.render(<Docs/>, document.getElementById("content"));
  1. 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`
  2. 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> 
  1. 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/
  1. 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!








DownloadsWeekly Downloads






Last publish


  • scottianstewart
  • keithluchtel
  • ceceppa
  • robwalkerco
  • gksander
  • sarahformidable
  • scott-rippey
  • michaelmerrill
  • sarmeyer
  • mariano-formidable
  • carlospaelinck
  • ryan.roemer
  • formidable-owner
  • eastridge
  • exogen
  • formidablelabs
  • carbonrobot
  • masiddee
  • thekenwheeler
  • colinmegill
  • coopy
  • kylecesmat
  • boygirl
  • chrisbolin