Herman 3.0.0

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.

Related

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 node-sass to be installed, if it isn’t already: npm install node-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 (relative to any includepaths) to include for all Sass examples:

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

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 node-sass docs). You can override this with the outputstyle option:

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

Example

scss
.sass {
  &-nesting {
    content: 'Example: Compiling Sass...';
  }
}
css compiled
.sass-nesting {
  content: 'Example: Compiling Sass...';
}

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
    }
  }
});

Example

njk
{% import 'utility.macros.njk' as utility %}

{{ utility.link_if('This is a link', '#0') }}<br />
{{ utility.link_if('This is not a link', none) }}
html compiled
<a href="#0">This is a link</a>
<br />
<span>This is not a link</span>