Add support for local() and data-URIs in font previews.

.babelrc.js

@@ -3,7 +3,7 @@
 'use strict';
 
 const env = process.env.BABEL_ENV;
-const plugins = [];
+const plugins = ['./arrow-function-coverage-fix.js'];
 if (env === 'test') {
   plugins.push(['istanbul', { include: ['assets/js/*!(init).js'] }]);
 }

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Herman Changelog
 
 
+## Unreleased
+
+- 🚀 NEW: Add support for CSS `@font-face` `local()` src in font previews --
+  [#173](https://github.com/oddbird/sassdoc-theme-herman/issues/173)
+- 🚀 NEW: Add support for embedded data-URI (`data:...`) font previews --
+  [#197](https://github.com/oddbird/sassdoc-theme-herman/issues/197)
+- 💥 BREAKING: Remove `@font` annotation "formats" option (`{woff, woff2}`) --
+  replaced by `formats` key in font Sass map
+- 💥 BREAKING: Ignore `@font` Sass map top-level `svgid` option --
+  replaced by variant-specific nested `svgid` option
+- 🐛 BUGFIX: `@font` previews for local/embedded fonts now sort `@font-face`
+  src according to [fontsquirrel generated syntax](https://www.fontsquirrel.com/tools/webfont-generator)
+- 🏠 INTERNAL: Use [forked version of scss-comment-parser](https://github.com/jgerigmeyer/scss-comment-parser/tree/fix-semicolon)
+  allowing semicolons in documented variable values (e.g. data-URIs) --
+  [#254](https://github.com/oddbird/sassdoc-theme-herman/issues/254)
+
+
 ## 1.1.0: 2018-01-17
 
 - 🚀 NEW: Extend SassDoc [groups](http://sassdoc.com/configuration/#groups)

README.md

@@ -8,7 +8,7 @@
 > Documentation should become the default --
 > an integrated part of the development process.
 >
-> <cite>---<a href="http://oddbird.net/birds/#bird-miriam">Miriam Suzanne</a></cite>
+> <cite>---<a href="http://oddbird.net/authors/miriam/">Miriam Suzanne</a></cite>
 
 At [OddBird][oddbird],
 we wanted better tools for documenting

arrow-function-coverage-fix.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// Restore old babylon behavior for istanbul.
+// https://github.com/babel/babel/pull/6836
+// https://github.com/istanbuljs/istanbuljs/issues/119
+module.exports = function hacks() {
+  return {
+    visitor: {
+      Program(programPath) {
+        programPath.traverse({
+          ArrowFunctionExpression(path) {
+            const node = path.node;
+            node.expression = node.body.type !== 'BlockStatement';
+          },
+        });
+      },
+    },
+  };
+};

docs/CHANGELOG.html

@@ -295,6 +295,22 @@ <h3 class="nav-title">
 
   <div class="text-block">
     <h1 id="herman-changelog">Herman Changelog</h1>
+<h2 id="unreleased">Unreleased</h2>
+<ul>
+<li>🚀 NEW: Add support for CSS <code>@font-face</code> <code>local()</code> src in font previews –
+<a href="https://github.com/oddbird/sassdoc-theme-herman/issues/173">#173</a></li>
+<li>🚀 NEW: Add support for embedded data-URI (<code>data:...</code>) font previews –
+<a href="https://github.com/oddbird/sassdoc-theme-herman/issues/197">#197</a></li>
+<li>💥 BREAKING: Remove <code>@font</code> annotation “formats” option (<code>{woff, woff2}</code>) –
+replaced by <code>formats</code> key in font Sass<span class="widont">&nbsp;</span>map</li>
+<li>💥 BREAKING: Ignore <code>@font</code> Sass map top-level <code>svgid</code> option –
+replaced by variant-specific nested <code>svgid</code> option</li>
+<li>🐛 BUGFIX: <code>@font</code> previews for local/embedded fonts now sort <code>@font-face</code>
+src according to <a href="https://www.fontsquirrel.com/tools/webfont-generator">fontsquirrel generated<span class="widont">&nbsp;</span>syntax</a></li>
+<li>🏠 INTERNAL: Use <a href="https://github.com/jgerigmeyer/scss-comment-parser/tree/fix-semicolon">forked version of scss-comment-parser</a>
+allowing semicolons in documented variable values (e.g. data-URIs) –
+<a href="https://github.com/oddbird/sassdoc-theme-herman/issues/254">#254</a></li>
+</ul>
 <h2 id="1-1-0-2018-01-17">1.1.0: 2018-01-17</h2>
 <ul>
 <li>🚀 NEW: Extend SassDoc <a href="http://sassdoc.com/configuration/#groups">groups</a>

docs/api_json-export.html

@@ -604,13 +604,13 @@ <h3 id="map-structure">Map structure</h3>
     /* color maps */
   );
   'sizes': (
-    /* color maps */
+    /* size maps */
   );
   'ratios': (
-    /* color maps */
+    /* ratio maps */
   );
   'fonts': (
-    /* color maps */
+    /* font maps */
   );
 );
 </code></pre>
@@ -647,20 +647,43 @@ <h3 id="fonts">Fonts</h3>
 since font-previews display a single font at a time.
 The data map<span class="widont">&nbsp;</span>accepts:</p>
 <ul>
-<li><code>name</code>: how the font should be referenced in CSS (if omitted, defaults to top-level<span class="widont">&nbsp;</span>key)</li>
+<li><code>name</code>: how the font should be referenced in CSS
+(if omitted, defaults to top-level<span class="widont">&nbsp;</span>key)</li>
 <li><code>stack</code>: optional string or list of font-stack<span class="widont">&nbsp;</span>fallbacks</li>
 <li><code>source</code>: link to more information on the font,
 or typekit/googlefonts as<span class="widont">&nbsp;</span>useful</li>
-<li><code>svgid</code>: optional suffix value for local SVG font <code>src</code>, e.g. <code>font-file.svg#svgid</code> (if omitted, defaults to <code>name</code>)</li>
+<li><code>formats</code>: font format (or space-separated list of font formats)
+for locally-hosted fonts – valid format options are
+<code>ttf</code>, <code>otf</code>, <code>woff</code>, <code>woff2</code>, <code>svg</code>, <code>svgz</code>, and <code>eot</code></li>
 <li><code>&lt;variant&gt;</code>: describe any number of relative paths to locally-hosted
-font-files per variant: e.g. <code>regular</code>, <code>bold italic</code>, etc.</li>
+font-files, or embedded <code>data:...</code> font strings
+per variant (e.g. <code>normal</code>, <code>bold italic</code>, etc.) –
+optionally, the value can also be a nested object
+with the following variant-specific keys:
+<ul>
+<li><code>path</code>: variant-specific relative path to locally-hosted<span class="widont">&nbsp;</span>font-files</li>
+<li><code>local</code>: font name (or space-separated list of font names)
+used to look for local user<span class="widont">&nbsp;</span>fonts</li>
+<li><code>svgid</code>: optional suffix value for local SVG font <code>src</code>,
+e.g. <code>font-file.svg#svgid</code> (if omitted, defaults to <code>name</code>)</li>
+<li><code>&lt;format&gt;</code>: describe any number of relative paths to locally-hosted
+font-files, or embedded <code>data:...</code> font strings
+per format (e.g. <code>ttf</code>, <code>otf</code>, <code>woff2</code>, etc.)</li>
+</ul>
+</li>
 </ul>
 <pre><code class="lang-scss">'body-font': (
   'name': 'Source Sans Pro',
-  'source': 'https://github.com/adobe-fonts/source-sans-pro'
   'stack': ('Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif'),
-  'regular': 'sans/sourcesanspro-regular-webfont',
+  'formats': 'woff' 'woff2' 'ttf',
+  'normal': 'sans/sourcesanspro-regular-webfont',
   'italic': 'sans/sourcesanspro-italic-webfont',
+  'bold': (
+    'path': 'sans/sourcesanspro-bold-webfont',
+    'local': 'source-sans-pro-bold',
+    'ttf': 'sans-ttf/sourcesanspro-bold-webfont',
+    'woff': 'data:application/x-font-woff;charset=utf-8;base64...'
+  ),
 )
 </code></pre>
 
@@ -753,8 +776,15 @@ <h3 class="item-subtitle">
     &#39;body-font&#39;: (
       &#39;name&#39;: &#39;Source Sans Pro&#39;,
       &#39;stack&#39;: (&#39;Helvetica Neue&#39;, &#39;Helvetica&#39;, &#39;Arial&#39;, &#39;sans-serif&#39;),
-      &#39;regular&#39;: &#39;sans/sourcesanspro-regular-webfont&#39;,
+      &#39;formats&#39;: &#39;woff&#39; &#39;woff2&#39; &#39;ttf&#39;,
+      &#39;normal&#39;: &#39;sans/sourcesanspro-regular-webfont&#39;,
       &#39;italic&#39;: &#39;sans/sourcesanspro-italic-webfont&#39;,
+      &#39;bold&#39;: (
+        &#39;path&#39;: &#39;sans/sourcesanspro-bold-webfont&#39;,
+        &#39;local&#39;: &#39;source-sans-pro-bold&#39;,
+        &#39;ttf&#39;: &#39;sans-ttf/sourcesanspro-bold-webfont&#39;,
+        &#39;woff&#39;: &#39;data:application/x-font-woff;charset=utf-8;base64...&#39;
+      ),
     ),
   ),
   &#39;sizes&#39;: (