Herman 2.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.

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

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>