Skip to content

Latest commit

 

History

History
326 lines (242 loc) · 9.65 KB

CONFIGURATION.md

File metadata and controls

326 lines (242 loc) · 9.65 KB
Raw

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.

extraLinks

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

If the customPreviewCSS option is not set, any CSS custom properties or font-related declarations (e.g. font-family or font-size) declared in html, body, or :root -- and all @font-face at-rules -- in this customCSS stylesheet will be included in rendered @font, @ratios, @sizes, and @colors 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 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 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.

customPreviewCSS

  • Type: String
  • Default: ''

Relative path to a custom CSS file containing CSS custom properties or font-related CSS to be included in rendered @font, @ratios, @sizes, and @colors annotations. Custom properties and font declarations must be declared on html, body, or :root.

If this option is not set, the customCSS option will be used instead.

customSourceMap

  • Type: String or false
  • Default: customCSS + '.map' if customCSS option is defined, otherwise ''

Relative path to a custom CSS source-map file, presumably referenced from the file specified in the customCSS option. If customCSS is defined, this defaults to the customCSS path with '.map' appended. To opt out of this feature, set customSourceMap to false.

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

  • Type: String or Sass implementation instance
  • Default: 'sass'

Determines the Sass implementation (defaults to sass) to use for Sass compilation if using @example scss annotation. This option expects a string that matches the name of an available Dart Sass implementation (e.g. sass or sass-embedded), or a Dart Sass instance itself.

sass.jsonFile

  • Type: String
  • Default: ''

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

Relative path to a sass-json file (created with the 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.use

  • Type: Array
  • Default: []

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

Each item in the array can be a string (path to the file) or an object with file and namespace keys (to @use "<file>" as <namespace>):

# .sassdocrc
herman:
  sass:
    use:
      - 'config/tools'
      - file: 'config/other-tools'
        namespace: 'my-tools'
    sassOptions:
      loadPaths:
        - 'static/sass'

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

sass.sassOptions

  • Type: Object
  • Default: { importers: [new sass.NodePackageImporter()] }

Options (e.g. importers, loadPaths, or style) that are passed directly through to Dart Sass when compiling @example sass/scss annotations. See the Dart Sass documentation for more info.

By default, importers is set to an array containing the Node.js package importer, which supports pkg: imports to resolve @use and @import for external modules installed via npm or Yarn. If sass.sassOptions.importers is set (even as an empty array importers: []), it will override the default importer.