Herman 5.0.0-beta.0

Herman Changelog

5.0.0-beta.0: 2022-08-12

  • 💥 BREAKING: Disable all autofill annotations for comments that Herman treats as “prose” (i.e. separated from documented code by one or more newlines).
  • 💥 BREAKING: Drop support for Node < 14
  • 💥 BREAKING: utilities.add() no longer supports map-compilation functions and arguments, since there are two reasonable approaches. Maps that need to be compiled for Herman must now be compiled before they are added. That can still be done using either:
    • 🚀 NEW: utilities.each-value() will pass each value of a map through a given function (this is the previous behavior of passing args to add())
    • 🚀 NEW: utilities.each-key() will pass each key of a map through a given function
  • 🚀 NEW: Allow utilities.add() to merge data, instead of override
  • 🚀 NEW: Add customSourceMap option (default: customCSS option + .map) to allow copying source-map file along with customCSS file
  • 🚀 NEW: Font-map variant keys can be comma-separated – #338
  • 🚀 NEW: Add support for non-standard CSS font-weight names – #250
  • 🚀 NEW: Length keywords in @sizes {ruler} maps will display as a border
  • 🏠 INTERNAL: Include source-maps with Herman JS & CSS assets
  • 🏠 INTERNAL: Upgrade dependencies
  • 🏠 INTERNAL: Remove documentation static-site from repository
  • 🏠 INTERNAL: Limit size of NPM package
  • 📝 DOCS: Add samples for @use '~/sassdoc-theme-herman/scss/utilities';

4.0.2: 2021-05-07

  • 🐛 BUGFIX: Fix build error on package install

4.0.1: 2021-05-07

  • 🐛 BUGFIX: Pin cheerio dependency to fix breaking change
  • 🏠 INTERNAL: Upgrade dependencies

4.0.0: 2021-01-04

  • No changes from v4.0.0-rc.1

4.0.0-rc.1: 2021-01-04

  • 💥 BREAKING: Drop support for Node < 10
  • 💥 BREAKING: Switch to Dart Sass throughout, and use as default sass.implementation option
  • 💥 BREAKING: Convert Herman-specific options to camelCase (fontPath, nunjucks.templatePath, sass.jsonFile, sass.includePaths, sass.outputStyle)
  • 💥 BREAKING: Herman no longer automatically optimizes SVG icons using SVGO
  • 💥 BREAKING: Remove herman- prefix from Sass JSON utilities:
    • herman-add() => add()
    • herman-export() => export()
    • herman-map-compile() => compile()
  • 🚀 NEW: Add support for using namespaced Sass modules in @example scss annotations with sass.use option
  • 🚀 NEW: Default Sass importer (used by @example scss) now supports ~ imports of external modules in Yarn 2 PnP environments
  • 🚀 NEW: Allow using custom Sass importer with @example scss via new sass.importer option
  • 📝 DOCS: Fix broken links in Changelog
  • 🏠 INTERNAL: Upgrade dependencies:
    • Switch to Yarn 2
    • Remove gulp-imagemin and svgo – 343
    • Replace through2 with Node’s native readable-stream

3.2.0: 2020-06-16

  • 🐛 BUGFIX: Use iframes to properly render size-related previews (all @font, @ratios, and @sizes previews are now each rendered in an <iframe>, receiving user-supplied customCSS and a limited subset of Herman styles) – #339
  • 🏠 INTERNAL: Upgrade dependencies

3.1.0: 2020-04-24

  • 🚀 NEW: Add sass.implementation (default: node-sass) and sass.use (default: []) options to support Dart Sass – #342 and #341
  • 🏠 INTERNAL: Use Dart Sass to compile Herman styles
  • 🏠 INTERNAL: Upgrade dependencies

3.0.2: 2019-01-09

  • 🐛 BUGFIX: Allow local system fonts without formats – #336

3.0.1: 2019-01-07

  • 🐛 BUGFIX: Improve error message when reading external files – #311
  • 🏠 INTERNAL: Remove node-sass from peerDependencies
  • 🏠 INTERNAL: Upgrade dependencies

3.0.0: 2018-04-09

  • 💥 BREAKING: Move node-sass to peerDependencies
  • 🐛 BUGFIX: Do not require node-sass if @example scss is not used
  • 🏠 INTERNAL: Upgrade dev dependencies

2.1.0: 2018-04-02

  • 🚀 NEW: Add sass.outputStyle option (default: expanded) – #263
  • 🐛 BUGFIX: Escape backslashes in herman-export string values
  • 🐛 BUGFIX: Fix bug if annotations try to access missing env.herman – #273
  • 🐛 BUGFIX: Fix bug displaying tabs in <code> blocks – #271
  • 🐛 BUGFIX: Fix bugs in customCSS URL re-writing – #265, #266
  • 🏠 INTERNAL: Run tests on Windows – #270
  • 🏠 INTERNAL: Upgrade dependencies

2.0.0: 2018-01-31

  • 🚀 NEW: Add support for CSS @font-face local() src in font previews – #173
  • 🚀 NEW: Add support for embedded data-URI (data:...) font previews – #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
  • 🏠 INTERNAL: Use forked version of scss-comment-parser allowing semicolons in documented variable values (e.g. data-URIs) – #254

1.1.0: 2018-01-17

  • 🚀 NEW: Extend SassDoc groups setting to allow nesting groups in named categories – #228
  • 🐛 BUGFIX: Fix herman-export including incorrectly escaped quotes (especially when compiled with Ruby Sass) – #236
  • 🏠 INTERNAL: Remove deprecated dev-dependency gulp-util
  • 🏠 INTERNAL: Upgrade dependencies

1.0.1: 2018-01-03

  • 📝 DOCS: Document Herman-specific styles and patterns.
  • 🐛 BUGFIX: Open links within iframe in parent context (<base target="_parent">).

🎉 1.0.0: 2017-12-15 🎉

No changes from v1.0.0-rc.8. Changes since v0.5.5:

🚀 New Features

  • Support for remaining SassDoc annotations: @throw, @return, @output, @content, @since, @deprecated, @author, @todo, @type, @alias (and aliased callback), used-by (@require annotation callbacks)
  • New @font, @colors, @sizes, and @ratios annotations (replace @preview annotation) – #206
  • Support for SassDoc googleAnalytics and trackingCode options – #215
  • Site-wide search – #28
  • extraDocs option: adds additional files (parsed as Markdown) – #117
  • extraLinks option: adds external links to sidebar nav – #175
  • displayColors option: customizes color formats displayed with @colors annotation
  • customHTML option: HTML to include in rendered @example annotations (replaces minifiedIcons option)
  • Support “prose” SassDoc comments, that aren’t attached to a Sass block (parsed as Markdown)
  • Sass: herman-export mixin – JSON-export functionality is now built-in Sass-json-export integration should continue to work as expected
  • Sass: herman-add($key, $map, $args…) function – adds maps directly to $herman, with optional function/args to compile raw map values

💥 Breaking Changes

  • Require Node >= 6.0.0
  • Remove @preview annotation (replaced by new @font, @colors, @sizes, and @ratios annotations) – #206
  • Remove @macro annotation (replaced by @example njk) – #182
  • @icons annotation now only requires path to a folder of SVG icons: relative to the project directory, no longer relative to the templatepath option – #47
  • Herman-specific options are now nested under top-level herman object in SassDoc configuration
  • Remove minifiedIcons option (replaced with new customHTML option)
  • Remove customHead option (replaced by multiline @font annotation)
  • Sass-specific options are now nested under herman.sass object
  • Remove top-level templatepath and nunjucksEnv options – now nested under new nunjucks options object: nunjucks.templatepath and nunjucks.environment
  • customCSS is only included in rendered @example annotation iframes
  • Group navigation is now ordered according to config groups order – #150
  • Preserve the original order of SassDoc comments, rather than grouping by type
  • Sass: $herman export map structure is now organized by type, in nested maps: colors, sizes, ratios, and fonts
  • Sass: herman-add mixin now requires an initial $type argument, in order to assign the given data to the proper nested data-type map
  • Sass: Rename $json to $herman for clearer name-spacing
  • Sass: _herman-inspect, and _herman-str-replace are now considered private functions
  • Sass: herman-map-compile always returns inspected (json-ready) values, and now accepts function args
  • Sass: Remove herman-add-colors/-sizes/-ratios/-font from utils

🐛 Bug Fixes

  • Return correct promise from theme function (fixes early resolution)
  • UsedBy list is aware of display.alias to unlink hidden aliases
  • Do not link to internal @access private items if display option is set to access: ['public']
  • Fix assets referenced with relative urls in client-provided customCSS for @example annotations – #174
  • Fix blocks with multi-line selectors and custom @name annotations – #140
  • Fix broken internal links – #106
  • Do not break layout on fonts with single-item stack – #172

💅 Polish

  • Add attribution/link to Herman/OddBird in nav footer (hidden if display.watermark is set to false) – #154
  • Replace marked with markdown-it for Markdown parsing with quote beautification – #119
  • Add “widont” text transformations with typogr
  • Pretty-print compiled HTML/Nunjucks with html prettyprinter
  • Add Herman logo for default favicon – #155
  • Group identical colors in @colors color-palette – #123
  • Display @example source and compiled code (njk and html; scss and css) side-by-side – #65, #37
  • Display links on index pages to project home and source, when defined in the project package.json – #91
  • Clean up display of parameters and properties – #53, #49, #55
  • Re-brand with sidebar navigation – #58, #69
  • Various branding and style improvements

🏠 Internal

  • Use forked version of CDocParser preserving /// within comments – #212
  • Use installJinjaCompat for default Nunjucks environment
  • Bundle static assets with Webpack; precompile JS with Babel – #205
  • Do not minify compiled HTML assets – #186
  • Move documentation to docs/ and include in repo
  • Flesh out Herman documentation
  • Use GoogleFonts rather than shipping font files
  • Add 100% test coverage
  • Update dependencies

1.0.0-rc.8: 2017-12-14

  • CHANGE: Use installJinjaCompat for default Nunjucks environment.
  • BUGFIX: Fix prettyPrint for compiled HTML/Nunjucks.

1.0.0-rc.7: 2017-12-12

  • NEW: Support SassDoc googleAnalytics and trackingCode options – #215
  • CHANGE: Use forked version of CDocParser preserving /// within comments – #212
  • BUGFIX: Fix paths to custom assets referenced from customCSS.

1.0.0-rc.6: 2017-12-04

  • BUGFIX: Fix search result page links.

1.0.0-rc.5: 2017-12-04

  • BUGFIX: Fix fetching site-search JSON file.

1.0.0-rc.4: 2017-12-04

  • BUGFIX: Fix broken site-search action attribute.
  • CHANGE: Hide Herman watermark if SassDoc display.watermark is false.

1.0.0-rc.3: 2017-11-30

  • BUGFIX: Correct for overzealous npm-ignoring (fixes missing scss utilities).

1.0.0-rc.2: 2017-11-30

  • NEW: Add site-wide search – #28
  • CHANGE: Bundle static assets with Webpack; precompile JS with Babel – #205
  • BREAKING: Remove @preview annotation, split it into distinct @colors, @sizes, @ratios annotations. @colors, @ratios, and @sizes annotations accept optional one-word key argument instead of semicolon-separated key:value arguments. @sizes still accepts style argument, now in curly-brackets ({...}). count argument removed from @ratios annotation – #206
  • CHANGE: @font annotation accepts font name (first argument) without being wrapped in ' or ".

1.0.0-rc.1: 2017-11-24

  • NEW: Add additional files (parsed as Markdown) with extraDocs option – #117
  • CHANGE: JSON-export functionality is now built in using the herman-export mixin. Sass-json-export integration should continue to work as expected.
  • Updated dependencies.
  • BREAKING: Remove subprojects option; replace with extraLinks option – #175
  • BREAKING: Removed @macro annotation; use @example njk instead – #182
  • CHANGE: HTML assets are no longer minified – #186
  • CHANGE: Replace marked with markdown-it for Markdown parsing with quote beautification – #119
  • NEW: Add “widont” text transformations with typogr.
  • BUGFIX: Ensure consistent ordering of extraDocs.
  • BREAKING: @icons annotation only requires path to a folder of SVG icons – #47
  • BREAKING: Replace minifiedIcons option with customHTML option (only included in rendered @example annotations).
  • BREAKING: Nest templatepath and nunjucksEnv options under new nunjucks options object: nunjucks.templatepath and nunjucks.environment.
  • NEW: Add attribution/link to Herman/OddBird in nav footer – #154
  • CHANGE: Use Herman logo for favicon. – #155

1.0.0-alpha.15: 2017-10-30

  • BUGFIX: Do not error if local file (referenced from customCSS) is not found
  • BUGFIX: Do not output duplicate custom @font HTML in @example iframe

1.0.0-alpha.14: 2017-10-27

  • BREAKING: Remove accoutrement-add as a public utility, since Sass 3.5+ modular sytems will make it unusable.
  • Updated dependencies.
  • BUGFIX: Fix broken internal links – #106
  • BREAKING: Group navigation is ordered according to config groups order – #150
  • BUGFIX: Do not error if sass config option is undefined.
  • BUGFIX: Do not break layout on fonts with single-item stack – #172
  • BREAKING: @preview font-specimen is replaced by new @font annotation.
  • BREAKING: Removed customHead option; replaced by multiline @font annotation.
  • BUGFIX: Fix assets referenced with relative urls in client-provided customCSS for @example annotations – #174

1.0.0-alpha.13: 2017-09-25

  • BREAKING: $herman export map structure is now organized by type, in nested maps: colors, sizes, ratios, and fonts.
  • BREAKING: herman-add mixin now requires an initial $type argument, in order to assign the given data to the proper nested data-type map.

1.0.0-alpha.12: 2017-09-18

  • BUGFIX: Typo from updating to latest accoutrement-scale
  • BUGFIX: Improved internal logic for herman-map-compile mixin

1.0.0-alpha.11: 2017-09-18

  • BUGFIX: Do not error on prose blocks without item.context.name

1.0.0-alpha.10: 2017-09-14

  • BREAKING: Rename $json to $herman for clearer name-spacing
  • BREAKING: _herman-inspect, and _herman-str-replace are now considered private functions
  • BREAKING: herman-map-compile always returns inspected (json-ready) values, and now accepts function args
  • BREAKING: Remove herman-add-colors/-sizes/-ratios/-font from utils
  • BREAKING: Require Node >= 6.0.0
  • NEW: Use herman-add($key, $map, $args…) to add maps directly to $herman, with optional function/args to compile raw map values
  • NEW: Use accoutrement-add($type, $key, $map) to automate compilation of accoutrement (color, ratio, size, font) maps, while adding to both $herman and the appropriate accoutrement global ($colors, $ratios, $sizes, $fonts).
  • NEW: displayColors option (type: Array, default: ['hex', 'rgb', 'hsl'])
  • CHANGE: Group identical colors in color-palette – #123
  • BUGFIX: Fix blocks with multi-line selectors and custom @name annotations – #140
  • DOCS: Move to docs/ and include in repo.

1.0.0-alpha.9: 2017-06-29

  • BUGFIX: Remove non-standard html markup on prose blocks

1.0.0-alpha.8: 2017-06-28

  • BUGFIX: Remove un-used font files from distribution
  • Render sassdoc comments that aren’t attached to a Sass block as Markdown prose.
  • Preserve the original order of sassdoc comments rather than grouping by type.

1.0.0-alpha.7: 2017-06-16

  • BUGFIX: Render icon previews in iframes.
  • BUGFIX: Adjusted styles for navigation and text.
  • BUGFIX: Added styles for blockquotes.
  • BREAKING: minifiedIcons option and the first argument to the @icons annotation are both paths relative to the project directory, no longer relative to the templatepath option.

1.0.0-alpha.6: 2017-06-14

  • BREAKING: Render examples in iframes and only include custom CSS in those iframes, for better isolation.

1.0.0-alpha.5: 2017-06-08

  • BUGFIX: Style cleanup for code-blocks, examples, and properties
  • BUGFIX: UsedBy list is aware of display.alias to unlink hidden aliases

1.0.0-alpha.4: 2017-06-02

  • BREAKING: Move customHead option into herman options object.
  • BUGFIX: Return correct promise from theme function (fixes early resolution).

1.0.0-alpha.3: 2017-05-31

  • Use GoogleFonts rather than shipping font files
  • Add support for remaining SassDoc annotations: @throw, @return, @output, @content, @since, @deprecated, @author
  • Provide more samples

1.0.0-alpha.2: 2017-05-31

  • BUGFIX: Show compiled html/css @example even if only one type.

1.0.0-alpha.1: 2017-05-29

  • Display links on index pages to project home and source, when defined in the project package.json – #91
  • Clean up display of parameters and properties – #53 and #49 and #55
  • Display source and compiled code (njk and html; scss and css) side-by-side – #65
  • Add support for @todo annotation – #18
  • Add support for @type annotation – #19
  • Add support for @alias (and aliased callback) annotation – #5
  • Add support for used-by (@require annotation callbacks).
  • Show compiled CSS for @example scss annotations – #37
  • BREAKING: Nest Herman-specific options under herman object in sassdoc configuration, and Sass-specific options under herman.sass object.
  • Re-brand with sidebar navigation – #58 and #69.
  • Add support for rendering documentation from dependency subprojects – #61.
  • BUGFIX: Do not link to internal @access private items if display option is set to access: ['public'].
  • BUGFIX: Do not error if missing herman.subprojects option – #107.
  • BUGFIX: Do not error if missing herman options – #108.

0.5.5: 2017-02-22

0.5.4: 2017-01-16

  • Render type html examples to HTML – #45.

0.5.3: 2016-12-22

  • Prevent template render errors when data is missing. Fixes #44.

0.5.2: 2016-12-15

  • Change absolute @see links to relative paths, so we’re not assuming a root URL for the styleguide.
  • Add customHead option to add custom HTML to the <head>.

0.5.1: 2016-12-13

  • Add optional show argument for font-specimen previews – @preview font-specimen; show: regular, bold, bold italic – allowing you to override what variants are displayed in the specimen.

0.5.0: 2016-12-09

  • Add table output for @property annotation, similar to @parameter table output.
  • Standardize data-sassdoc-display='<annotation>' for annotation display blocks (previously a mix of data-sassdoc values), and data-sassdoc-table'<annotation>' for tables (previously data-sassdoc='<annotation>-table').

0.4.0: 2016-11-08

  • Inject preview data directly into HTML, so that previews don’t have to be styled locally
  • Add Sass Utilities file, for help with setting/exporting Sass data
  • herman-add-color mixin now exports hex, rgba, and hsla colors.
  • Simplified font previews don’t require size input
  • Color, font, ratio, and size previews accept key argument, in case the JSON key doesn’t match the variable name (most common for fonts)
  • Ratio preview accets count argument [1-10], determining how many instances of the ratio to display (default is 6)
  • Size preview accepts style argument [text | ruler | output-only], determining the type of preview to display (default is text, see scale for examples)

0.3.2: 2016-09-29

  • Mark imported minifiedIcons file as |safe.

0.3.1: 2016-09-14

  • Added nunjucksEnv option to use a custom nunjucks environment.
  • Added jinja syntax highlighting for @example njk code blocks.

0.3.0: 2016-08-17

  • Added rendering of @example annotations using the njk (nunjucks) language.
  • Removed rendering of macro examples using macroname_data.

0.2.1: 2015-12-23

  • Updated dependencies.

0.2.0: 2015-12-17

  • Add @icons annotation.
  • Add @preview annotation for color palettes and font specimens.
  • Add syntax highlighting of code blocks.

0.1.0: 2015-11-25

  • Initial release. @macro annotation and basic infrastructure.