Herman Changelog
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 withsass.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 newsass.importer
option - π DOCS: Fix broken links in Changelog
- π INTERNAL: Upgrade dependencies:
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-suppliedcustomCSS
and a limited subset of Herman styles) β #339 - π INTERNAL: Upgrade dependencies
3.1.0: 2020-04-24
- π NEW: Add
sass.implementation
(default:node-sass
) andsass.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
frompeerDependencies
- π INTERNAL: Upgrade dependencies
3.0.0: 2018-04-09
- π₯ BREAKING: Move
node-sass
topeerDependencies
- π 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 byformats
key in font Sass map - π₯ BREAKING: Ignore
@font
Sass map top-levelsvgid
option β replaced by variant-specific nestedsvgid
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
andtrackingCode
options β #215 - Site-wide search β #28
extraDocs
option: adds additional files (parsed as Markdown) β #117extraLinks
option: adds external links to sidebar nav β #175displayColors
option: customizes color formats displayed with@colors
annotationcustomHTML
option: HTML to include in rendered@example
annotations (replacesminifiedIcons
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 thetemplatepath
option β #47- Herman-specific options are now nested under top-level
herman
object in SassDoc configuration - Remove
minifiedIcons
option (replaced with newcustomHTML
option) - Remove
customHead
option (replaced by multiline@font
annotation) - Sass-specific options are now nested under
herman.sass
object - Remove top-level
templatepath
andnunjucksEnv
options β now nested under newnunjucks
options object:nunjucks.templatepath
andnunjucks.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
, andfonts
- 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 ofdisplay.alias
to unlink hidden aliases- Do not link to internal
@access private
items ifdisplay
option is set toaccess: ['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 tofalse
) β #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
andtrackingCode
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
isfalse
.
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-separatedkey:value
arguments.@sizes
still acceptsstyle
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 withextraLinks
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 withcustomHTML
option (only included in rendered@example
annotations). - BREAKING: Nest
templatepath
andnunjucksEnv
options under newnunjucks
options object:nunjucks.templatepath
andnunjucks.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 isundefined
. - 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
, andfonts
. - 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 thetemplatepath
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 intoherman
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 underherman.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 ifdisplay
option is set toaccess: ['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
- Fix @example macro to work with sassdoc v2.2.0. See https://github.com/SassDoc/sassdoc/commit/842847493f9644e50f9e2ce783eacf886ccf69a0.
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 ofdata-sassdoc
values), anddata-sassdoc-table'<annotation>'
for tables (previouslydata-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 is6
) - Size preview accepts
style
argument [text
|ruler
|output-only
], determining the type of preview to display (default istext
, 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.