Rendering SassDoc examples

SassDoc provides the @example annotation for displaying example Sass code. We’ve expanded their feature to show compiled CSS alongside the Sass input, compile Nunjucks examples for templating, and render any input-or-compiled HTML so you can see the results.

The resulting annotation syntax is identical to the original SassDoc feature. If you use the @example annotation with scss/sass (Sass) or njk (Nunjucks) languages, Herman will display the source of the example, along with the compiled output (and rendered html, if using njk or html languages). Both Sass & Nunjucks examples allow you to import external partials:

 /// This is a widget that we use on our site…
 /// @example scss
 ///   [data-widget] {
 ///     @include widget-style;
 ///   }
 /// @example njk
 ///  {% import 'macros.njk' as macros %}
 ///  {{ macros.widget(1, 2) }}
 @mixin widget-style { … }

Will display:

• Input Sass and Nunjucks code
• Compiled CSS and HTML output
• Rendered HTML in an iframe

We hope to support Vue components in the near future, with an API for supporting additional languages.

Compiling Sass/Scss

Example annotations with language set to sass or scss will be compiled by Herman, and display the output along with the source.

Note that Sass/Scss examples require sass to be installed, if it isn’t already: npm install sass.

All Sass examples must be complete and valid, with the ability to import Sass partials inside each example. In order for this to work with Sass/Scss, you must set an includePaths key in your sassdoc herman.sass configuration object – an array of places to look for Sass includes:

herman:
  sass:
    includePaths:
      - 'static/sass'
      - 'node_modules'

You can also set an array of default includes or use (relative to any includePaths) to include for all Sass examples:

To @import files:

# .sassdocrc (yaml)
herman:
  sass:
    includePaths:
      - 'static/sass'
    includes:
      - 'utilities'
      - 'config'

Or to @use files:

# .sassdocrc (yaml)
herman:
  sass:
    includePaths:
      - 'static/sass'
    use:
      - 'config/tools'
      - file: 'config/other-tools'
        namespace: 'my-tools'

Generally, included Sass files should not contain any CSS output of their own, since all compiled output will be displayed with the @example.

By default, the CSS output will be “expanded” (see the Sass docs). You can override this with the outputStyle option:

# .sassdocrc (yaml)
herman:
  sass:
    outputStyle: 'compressed'

Compiling Nunjucks

Example annotations with language set to njk can also be compiled. In order for this to work, you must either specify a nunjucks.templatePath (the path where Nunjucks will look to import templates), or a nunjucks.environment (custom Nunjucks environment). Using a custom environment is particularly useful if your macros contain custom filters. Either can be established in your sassdoc herman configuration object:

Setting nunjucks.templatePath:

# .sassdocrc (yaml)
herman:
  nunjucks:
    templatePath: 'templates'

Setting nunjucks.environment:

This is only possible if using the SassDoc Node API.

const nunjucks = require('nunjucks');
const sassdoc = require('sassdoc');

const nunjucksEnv = nunjucks.configure('./templates');

sassdoc(src, {
  theme: 'herman',
  herman: {
    nunjucks: {
      environment: nunjucksEnv
    }
  }
});