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:

  module.exports = {
    // ...
    components: './components/**/[A-Z]*.js',
  };

• 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.
  • sections (optional) — array of subsections.

  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: 'Documentation',
        sections: [
          {
            name: 'Installation',
            content: 'docs/installation.md',
          },
          {
            name: 'Configuration',
            content: 'docs/configuration.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). These components won’t be accessible from other examples unless you manually require them.

• 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.

• contextDependencies
  Type: Array of String, optional
  Array of strings that allow you to specify absolute paths of directories to watch for additions or removals of components. If you do not set this, styleguidist will determine the single directory that all of your components have in common and watch that.

  module.exports = {
    // ...
    contextDependencies: [
      path.resolve(__dirname, 'lib/components'),
    ],
    // ...
  }

• 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.

• previewDelay
  Type: Number, default: 500
  Debounce time used before render the changes from the editor. While inserting code the preview will not be updated.

• 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(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';:

  const path = require('path');
  module.exports = {
    // ...
    getComponentPathLine: function(componentPath) {
      const name = path.basename(componentPath, '.js');
      const 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(webpackConfig, env) {
      if (env === 'development') {
        // Modify config...
      }
      return webpackConfig;
    },
  };

  See FAQ for examples.

• configureServer
  Type: Function, optional
  Function that allows you to add endpoints to the underlying express server:

  module.exports = {
    // ...
    configureServer(app) {
       // `app` is the instance of the express server running react-styleguidist
    	app.get('/custom-endpoint', (req, res) => {
    		res.status(200).send({ response: 'Server invoked' });
    	});
    },
  };

  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(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, default: [react-docgen-displayname-handler]
  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.

  Also note that the default handler, react-docgen-displayname-handler should be included to better support higher order components.

  module.exports = {
    // ...
    handlers: require('react-docgen').defaultHandlers.concat(
      (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');
        }
      },
      // To better support higher order components
      require('react-docgen-displayname-handler').default,
    ),
  };