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
$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
/// @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)
font-family: 'Source Code Pro', Consolas, Menlo, 'Courier New', monospace, sans-serif;$demo-local
$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)
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.