Configuration.md

Configuration

You can change settings in the styleguide.config.js file in your project’s root folder.

• components
  Type: String or Function, required unless sections is provided
  

  • when String: a glob pattern that matches all your component modules. Relative to config folder.
  • when Function: a function that returns an array of module paths.

  If your components look like components/Button.js or components/Button/Button.js or components/Button/index.js:

  module.exports = {
    // ...
    components: './components/**/*.js',
  };

  If your components look like components/Button/Button.js + components/Button/index.js:

  var path = require('path');
  var glob = require('glob');
  module.exports = {
    // ...
    components: function() {
      return glob.sync(path.resolve(__dirname, 'lib/components/**/*.js')).filter(function(module) {
        return /\/[A-Z]\w*\.js$/.test(module);
      });
    },
  };

• sections
  Type: Array

  Allows components to be grouped into sections with a title and optional overview content. Sections can also be content only, with no associated components (for example, a textual introduction). A section definition consists of:
  

  • name — the title of the section.
  • content (optional) — location of a Markdown file containing the overview content.
  • components (optional) — a string or function returning a list of components. The same rules apply as for the root components option.

  Configuring a style guide with a textual introduction section, then a UI section would look like:

  module.exports = {
    // ...
    sections: [
      {name: 'Introduction', content: 'docs/introduction.md'},
      {name: 'UI Components', content: 'docs/ui.md', components: 'lib/components/ui/*.js'},
    ],
  };

• skipComponentsWithoutExample
  Type: Boolean, default: false
  Ignore components that don’t have an example file (as determined by getExampleFilename).

• defaultExample
  Type: Boolean or String, default: false
  For components that do not have an example, a default one can be used. When set to true, the DefaultExample.md is used, or you can provide the path to your own example Markdown file as a String.

  When writing your own default example file, __COMPONENT__ will be replaced by the actual component name at compile-time.

• showCode
  Type: Boolean, default: false
  Show or hide example code initially. It can be toggled in the UI by clicking the show/hide code toggle button underneath each example.

• styleguideDir
  Type: String, default: styleguide
  Folder for static HTML style guide generated with styleguidist build command.

• assetsDir
  Type: String, optional
  Your application static assets folder, will be accessible as / in the style guide dev-server.

• template
  Type: String, default: src/templates/index.html
  HTML file to use as the template for the output.

• title
  Type: String, default: Style guide
  Style guide title.

• serverHost
  Type: String, default: localhost
  Dev server host name.

• serverPort
  Type: Number, default: 3000
  Dev server port.

• highlightTheme
  Type: String, default: base16-light
  CodeMirror theme name to use for syntax highlighting in examples.

• getExampleFilename
  Type: Function, default: finds Readme.md in the component folder
  Function that returns examples file path for a given component path.

  For example, instead of Readme.md you can use ComponentName.examples.md:

  module.exports = {
    // ...
    getExampleFilename: function(componentpath) {
      return componentpath.replace(/\.jsx?$/,   '.examples.md');
    },
  };

• getComponentPathLine
  Type: Function, default: optional
  Function that returns a component path line (displayed under the component name).

  For example, instead of components/Button/Button.js you can print import Button from 'components/Button';:

  var path = require('path');
  module.exports = {
    // ...
    getComponentPathLine: function(componentPath) {
      var name = path.basename(componentPath, '.js');
      var dir = path.dirname(componentPath);
      return 'import ' + name + ' from \'' + dir + '\';';
    },
  };

• updateWebpackConfig
  Type: Function, optional
  Function that allows you to modify Webpack config for style guide:

  module.exports = {
    // ...
    updateWebpackConfig: function(webpackConfig, env) {
      if (env === 'development') {
        // Modify config...
      }
      return webpackConfig;
    }
  };

  See FAQ for examples.

• propsParser
  Type: Function, optional
  Function that allows you to override the mechanism used to parse props from a source file. Default mechanism is using react-docgen to parse props.

  module.exports = {
    // ...
    propsParser: function(filePath, source) {
      return require('react-docgen').parse(source);
    },
  };

• resolver
  Type: Function, optional
  Function that allows you to override the mechanism used to identify classes/components to analyze. Default behaviour is to find a single exported component in each file and fail if more than one export is found. You can configure it to find all components or use a custom detection method. See the react-docgen resolver documentation for more information about resolvers.

  module.exports = {
    // ...
    resolver: require('react-docgen').resolver.findAllComponentDefinitions,
  };

• handlers
  Type: Array of Function, optional
  Array of functions used to process the discovered components and generate documentation objects. Default behaviours include discovering component documentation blocks, prop types and defaults. If setting this property, it is best to build from the default react-docgen handler list, such as in the example below. See the react-docgen handler documentation for more information about handlers.

  module.exports = {
    // ...
    handlers: require('react-docgen').defaultHandlers.concat(function(documentation, path) {
      // Calculate a display name for components based upon the declared class name.
      if (path.value.type == 'ClassDeclaration' && path.value.id.type === 'Identifier') {
        documentation.set('displayName', path.value.id.name);
  
        // Calculate the key required to find the component in the module exports
        if (path.parentPath.value.type === 'ExportNamedDeclaration') {
          documentation.set('path', path.value.id.name);
        }
      }
  
      // The component is the default export
      if (path.parentPath.value.type === 'ExportDefaultDeclaration') {
        documentation.set('path', 'default');
      }
    }),
  };