Herman 2.0.0

Herman Configuration Options

Nest all Herman-specific options under herman object in SassDoc config.

# .sassdocrc
theme: herman
herman:
  extraDocs:
    - './my-file.md'
// Node API
const sassdoc = require('sassdoc');

sassdoc('./scss', {
  theme: 'herman',
  herman: {
    extraDocs: ['./my-file.md']
  }
});

All relative paths are relative to the SassDoc config file or the cwd.

SassDoc: groups

  • Type: Object
  • Default: { undefined: 'General' }

Groups are a SassDoc configuration option, not nested inside the Herman block – though we provide some extra functionality on top of the SassDoc configuration. In addition to naming groups, we allow you to order them and create one level of sub-grouping:

# .sassdocrc
groups:
  # all items will be listed in the order given...
  api-config: Configuration
  api-json: Exporting Styles to JSON

  # nested objects will create named subgroups...
  Public API:
    api-colors: Color Palettes
    api-fonts: Font Specimens
    api-scale: Ratios & Sizes
  Design Tokens:
    config-colors: _Colors
    config-fonts: _Fonts

extraDocs

  • Type: Array
  • Default: []

Add files (parsed as Markdown) to your compiled documentation. Each value in the list should be an Object with keys path (relative path to the local file) and optionally name (displayed in the compiled documentation navigation – defaults to the filename), or a String path (in which case the filename will be displayed in the navigation).

This is useful for including additional documents, such as a changelog, quickstart guide, or instructions for contributing.

  • Type: Array
  • Default: []

Add external links to your compiled documentation navigation. Each value in the list should be an Object with keys name and url.

This is useful for linking to additional documentation for dependencies or other third-party integrations.

displayColors

  • Type: Array
  • Default: ['hex', 'rgb', 'hsl']

Configures which color value formats are shown when using the @colors annotation. Valid options: hex, rgb/rgba, hsl/hsla

customCSS

  • Type: String
  • Default: ''

Relative path to a custom CSS file, which will be included in the <head> of rendered @example annotations.

Notes:

  • If your custom CSS includes webfonts which require additional <script> or <style> tags (e.g. an external Google Fonts stylesheet or Adobe Typekit JavaScript), you must document those fonts with the @font annotation (providing the required extra HTML) for them to display properly within rendered @example annotations. See our @font documentation.
  • If your custom CSS contains internal links referenced with url(...) (e.g. local fonts or background images), Herman will attempt to copy in those assets so that they are available in your rendered @example annotations. This means that the paths must either be absolute, or relative to the location of the CSS file itself. If using Webpack to bundle your Herman customCSS, this likely means disabling the publicPath setting for this CSS file (e.g. publicPath: ''), or disabling Webpack’s url() pre-processing entirely.

customHTML

  • Type: String
  • Default: ''

Custom HTML string (or relative path to a file containing valid HTML) to include at the top of the generated <body> tag for all rendered @example html and @example njk annotations. See our @example documentation. This is particularly useful for including svg sprite sheets in example output.

fontpath

  • Type: String
  • Default: ''

Required if using @font annotation with local font files.

Relative path to a directory containing local font files. See our @font documentation.

nunjucks

  • Type: Object
  • Default: {}

Container for the following Nunjucks-related options:

nunjucks.templatepath

  • Type: String
  • Default: ''

Either nunjucks.templatepath or nunjucks.environment is required if using @example njk annotation.

Relative path to a directory containing Nunjucks templates.

nunjucks.environment

Either nunjucks.templatepath or nunjucks.environment is required if using @example njk annotation.

sass

  • Type: Object
  • Default: {}

Container for the following sass-related options:

sass.jsonfile

  • Type: String
  • Default: ''

Required if using @font, @colors, @ratios, or @sizes annotations.

Relative path to a sass-json file (created with the herman-export mixin). The JSON contents will be added under the sassjson key of the sassdoc context, and used to display colors, fonts, ratios, and sizes. See Exporting Styles to JSON.

sass.includepaths

  • Type: Array
  • Default: []

Array of paths used to resolve @import declarations. Passed through to node-sass when compiling @example sass/scss annotations. See our @example documentation.

sass.includes

  • Type: Array
  • Default: []

List of files (relative to any sass.includepaths) to @import for all @example sass/scss annotations. See our @example documentation.

This is useful for including any global Sass configuration and toolkit files that may be used by any example. It’s best to avoid files with output CSS, as that output will be displayed in every single Sass example.