Herman 6.0.1

Documenting fonts

Herman provides custom annotations for visualizing fonts, along with other design tokens. See the sass.jsonFile configuration to ensure that Herman has access to your exported Sass data.

Whether you use a webfont CDN like Typekit/Google Fonts, or locally-hosted font files, Herman can document and display your font-specimens. In order to do that, Herman will need a JSON map of font data – but we’ll start with individual font families, one hosted on a CDN, and the other hosted locally. Then we can build and export.

We store all font data in maps, with the syntax used by both Herman (for JSON exporting) and our [Accoutrement][ac] toolkit. See the font map documentation for details »

Each font family will be displayed individually, using the @font annotation:

/// @font my-font (normal, bold)

Let’s look at a few examples…

$demo-cdn

scss
$demo-cdn: (
  'name': 'Source Code Pro',
  'source': 'https://fonts.google.com/specimen/Source+Code+Pro',
  'stack': (
    'Consolas',
    'Menlo',
    'Courier New',
    monospace,
    sans-serif,
  ),
);

Displaying CDN-hosted webfonts

For remotely-hosted fonts, the @font annotation accepts three arguments:

/// @font font-key (list of, variants, to show)
///   <any html required for import>
  • The first argument is an optional one-word key which defaults to the map-variable name. That key will be used to access the data from JSON, so it doesn’t matter what key is used – as long as the key given here matches the group-name used when adding this data to $herman.
  • The second argument (in parentheses) is an optional comma-separated list of font variants to display in the preview. If omitted, it defaults to any variants included as keys in the font map itself.
  • The third argument (on the following line, nested with two spaces) is an optional html string – usually a <link> or <script> tag required to use the webfont. This code will be inserted into the rendered iframe <head> for this font preview and all Herman examples, making your webfont available to other components.

Example

scss
/// @font demo-cdn (normal, bold, bold italic)
///   <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:400,700" rel="stylesheet">

Font Preview Source Code Pro (demo-cdn)

css
font-family: 'Source Code Pro', Consolas, Menlo, 'Courier New', monospace, sans-serif;

$demo-local

scss
$demo-local: (
  'name': 'rockingham',
  'normal': (
    'path': 'rockingham/rockingham-regular-webfont',
    'local': 'rockingham-regular-webfont',
  ),
  'bold': 'rockingham/rockingham-bold-webfont',
  'italic': 'rockingham/rockingham-italic-webfont',
  'bold' 'italic': 'rockingham/rockingham-bolditalic-webfont',
  'stack': 'fantasy',
  'formats': 'woff2' 'woff' 'ttf',
);

Displaying local fonts

For locally-hosted fonts, the @font annotation accepts two arguments:

  • The first argument is an optional one-word key which defaults to the map-variable name. That key will be used to access the data from JSON, so it doesn’t matter what key is used – as long as the key given here matches the group-name used when adding this data to $herman.
  • The second argument (in parentheses) is an optional comma-separated list of font variants to display in the preview. If omitted, it defaults to all variants included as keys in the font map itself.
/// @font demo-local

In order for this to work, you must specify a fontPath (the path where Herman will look to import local font files), in your SassDoc herman configuration object.

# .sassdocrc (yaml)
herman:
  fontPath: 'fonts/'

Font Preview rockingham (demo-local)

css
font-family: rockingham, fantasy;

Add font data to $herman

In order to preview the $demo-cdn and $demo-local maps, we also need to export the data to JSON.

You can add data to the $herman export-map by hand, or use the provided add mixin to combine existing maps into the proper structure. See the font map documentation for details.

 @include add('font', 'demo-code', $demo-code);
 @include add('font', 'demo-local', $demo-local);

After adding your data to the $herman map, it can be converted to JSON using export.

Related

Accoutrement [external]

@mixin add()

@mixin export()