- 🐛 BUGFIX: Do not overwrite
ctx.emit
method -- #423 - 🏠 INTERNAL: Upgrade dependencies
- Add
sass.implementation
option (string
or Dart Sass instance) to specify the Dart Sass implementation to use for@example scss
annotations. (default:sass
). - Use faster Dart Sass
AsyncCompiler
API for@example scss
annotations. - Add
exports.sass
inpackage.json
for simplerpkg:
imports.
- Require Dart Sass
^1.71.0
for@example scss
annotations, using the new Node.js package importer insass.sassOptions.importers
by default. - Remove custom Sass importer that supported
~
imports for external modules. Replace~
withpkg:
to use the newer Dart Sass Node.js package importer. - Remove
sass.importers
option (usesass.sassOptions.importers
instead). - Remove deprecated
sass.includes
option (usesass.use
instead). - Drop support for Node < 18
- Use
sass-embedded
instead ofsass
internally - Replace "Source Sans Pro" font with "Source Sans 3"
- Upgrade to Yarn v4 (without PnP)
- Add Dependabot for dependency updates going forward
- Upgrade dependencies
- 🏠 INTERNAL: Upgrade dependencies
No changes from v5.0.0-beta.7
. Changes since v4.0.2
:
- Color previews are now rendered in an
<iframe>
which allows them to make use of user-supplied CSS custom properties (and a limited subset of Herman styles). Custom properties are made available via the newcustomPreviewCSS
or existingcustomCSS
options. To be included, custom properties must be declared onhtml
,body
, or:root
. - Length keywords in
@sizes {ruler}
maps now display as a border - Allow
utilities.add()
to merge data, instead of override utilities.each-value()
will pass each value of a map through a given function (this is the previous behavior of passing args toadd()
)utilities.each-key()
will pass each key of a map through a given function- Add
customSourceMap
option (default:customCSS
option +.map
) to allow copying source-map file along withcustomCSS
file - Font-map variant keys can be comma-separated -- #338
- Add support for non-standard CSS font-weight names -- #250
- Font, ratio, size, and color previews are now rendered without user-provided
stylesheets (to avoid style conflicts). CSS custom properties and font-related
CSS are made available via the new (🚀)
customPreviewCSS
or existingcustomCSS
options. To be included, declarations must be declared onhtml
,body
, or:root
in the stylesheet set viacustomPreviewCSS
orcustomCSS
settings. (All@font-face
at-rules are included.) - Require Dart Sass (
^1.45.0
) for@example scss
annotations, using the updated Dart Sass JavaScript API. Thesass.implementation
option is removed, along with support fornode-sass
. - Rename
sass.importer
option tosass.importers
, matching the Dart Sass option. - Remove
sass.includePaths
andsass.outputStyle
options. These are replaced with a newsass.sassOptions
option, which accepts any options that Dart Sass accepts (e.g.loadPaths
orstyle
). See the Dart Sass documentation for more details. 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 toadd()
) - 🚀 NEW:
utilities.each-key()
will pass each key of a map through a given function
- 🚀 NEW:
- Disable all
autofill
annotations for comments that Herman treats as "prose" (i.e. separated from documented code by one or more newlines). - Drop support for Node < 14
- Switch from tinycolor to colorjs.io for color conversions, to fix bug displaying colors that use hue angle notation.
- Add samples for
@use '~/sassdoc-theme-herman/scss/utilities';
- Replace Bluebird dependency with native promises.
- Replace CircleCI, Codecov, and AppVeyor with GitHub Actions
- Include source-maps with Herman JS & CSS assets
- Remove documentation static-site from repository and npm package
- Limit size of NPM package
- Upgrade dependencies
- 💥 BREAKING: Rename
customPropertiesCSS
option tocustomPreviewCSS
- 🐛 BUGFIX: Add missing font-related CSS (e.g.
font-family
,font-size
,@font-face
) to color, font, ratio, and size previews. To be included, declarations must be declared onhtml
,body
, or:root
in the stylesheet set viacustomPreviewCSS
orcustomCSS
settings. (All@font-face
at-rules are included.) - 🏠 INTERNAL: Upgrade dependencies
- 🐛 BUGFIX: Add missing CSS custom properties for font, ratio, and size previews
- 💥 BREAKING: Require Dart Sass (
^1.45.0
) for@example scss
annotations, using the updated Dart Sass JavaScript API. Thesass.implementation
option is removed, along with support fornode-sass
. - 💥 BREAKING: Rename
sass.importer
option tosass.importers
, matching the Dart Sass option. - 💥 BREAKING: Remove
sass.includePaths
andsass.outputStyle
options. These are replaced with a newsass.sassOptions
option, which accepts any options that Dart Sass accepts (e.g.loadPaths
orstyle
). See the Dart Sass documentation for more details. - 💥 BREAKING: Font, ratio, size, and color previews are now rendered without
user-provided stylesheets (to avoid style conflicts). CSS custom properties
are made available via the new (🚀)
customPropertiesCSS
or existingcustomCSS
options. To be included, custom properties must be declared onhtml
,body
, or:root
. - 🏠 INTERNAL: Replace Bluebird dependency with native promises.
- 🏠 INTERNAL: Upgrade dependencies
- 🐛 BUGFIX: Add missing styles for color previews
- 🚀 NEW: Color previews are now rendered in an
<iframe>
which allows them to make use of user-suppliedcustomCSS
and a limited subset of Herman styles. - 🐛 BUGFIX: Switch from tinycolor to colorjs.io for color conversions, to fix bug displaying colors that use hue angle notation.
- 🏠 INTERNAL: Remove documentation from npm package
- 🏠 INTERNAL: Upgrade dependencies
- 🏠 INTERNAL: Replace CircleCI, Codecov, and AppVeyor with GitHub Actions
- 🐛 BUGFIX: Add border color/style for length keywords in
@sizes {ruler}
maps - 🏠 INTERNAL: Upgrade dependencies
- 🚀 NEW: Length keywords in
@sizes {ruler}
maps will display as a border - 🏠 INTERNAL: Upgrade dependencies
- 💥 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 toadd()
) - 🚀 NEW:
utilities.each-key()
will pass each key of a map through a given function
- 🚀 NEW:
- 🚀 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 withcustomCSS
file - 🚀 NEW: Font-map variant keys can be comma-separated -- #338
- 🚀 NEW: Add support for non-standard CSS font-weight names -- #250
- 🏠 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';
- 🐛 BUGFIX: Fix build error on package install
- 🐛 BUGFIX: Pin cheerio dependency to fix breaking change
- 🏠 INTERNAL: Upgrade dependencies
- No changes from v4.0.0-rc.1
- 💥 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 PnP environments - 🚀 NEW: Allow using custom Sass importer with
@example scss
via newsass.importer
option - 📝 DOCS: Fix broken links in Changelog
- 🏠 INTERNAL: Upgrade dependencies:
- 🐛 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
- 🚀 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
- 🐛 BUGFIX: Allow local system fonts without
formats
-- #336
- 🐛 BUGFIX: Improve error message when reading external files -- #311
- 🏠 INTERNAL: Remove
node-sass
frompeerDependencies
- 🏠 INTERNAL: Upgrade dependencies
- 💥 BREAKING: Move
node-sass
topeerDependencies
- 🐛 BUGFIX: Do not require
node-sass
if@example scss
is not used - 🏠 INTERNAL: Upgrade dev dependencies
- 🚀 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
- 🚀 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
- 🚀 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
- 📝 DOCS: Document Herman-specific styles and patterns.
- 🐛 BUGFIX: Open links within iframe in parent context
(
<base target="_parent">
).
No changes from v1.0.0-rc.8
. Changes since v0.5.5
:
- 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
- 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
- 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
- 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
- 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
- CHANGE: Use
installJinjaCompat
for default Nunjucks environment. - BUGFIX: Fix prettyPrint for compiled HTML/Nunjucks.
- 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
.
- BUGFIX: Fix search result page links.
- BUGFIX: Fix fetching site-search JSON file.
- BUGFIX: Fix broken site-search action attribute.
- CHANGE: Hide Herman watermark if SassDoc
display.watermark
isfalse
.
- BUGFIX: Correct for overzealous npm-ignoring (fixes missing scss utilities).
- 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"
.
- 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
- BUGFIX: Do not error if local file (referenced from
customCSS
) is not found - BUGFIX: Do not output duplicate custom
@font
HTML in@example
iframe
- 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
- 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.
- BUGFIX: Typo from updating to latest accoutrement-scale
- BUGFIX: Improved internal logic for
herman-map-compile
mixin
- BUGFIX: Do not error on prose blocks without
item.context.name
- 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.
- BUGFIX: Remove non-standard html markup on prose blocks
- 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.
- 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.
- BREAKING: Render examples in iframes and only include custom CSS in those iframes, for better isolation.
- BUGFIX: Style cleanup for code-blocks, examples, and properties
- BUGFIX: UsedBy list is aware of
display.alias
to unlink hidden aliases
- BREAKING: Move
customHead
option intoherman
options object. - BUGFIX: Return correct promise from theme function (fixes early resolution).
- Use GoogleFonts rather than shipping font files
- Add support for remaining SassDoc annotations:
@throw
,@return
,@output
,@content
,@since
,@deprecated
,@author
- Provide more samples
- BUGFIX: Show compiled html/css @example even if only one type.
- 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.
- Fix @example macro to work with sassdoc v2.2.0. See https://github.com/SassDoc/sassdoc/commit/842847493f9644e50f9e2ce783eacf886ccf69a0.
- Render type
html
examples to HTML -- #45.
- Prevent template render errors when data is missing. Fixes #44.
- 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>
.
- 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.
- 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'
).
- 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)
- Mark imported
minifiedIcons
file as|safe
.
- Added
nunjucksEnv
option to use a custom nunjucks environment. - Added
jinja
syntax highlighting for@example njk
code blocks.
- Added rendering of @example annotations using the njk (nunjucks) language.
- Removed rendering of macro examples using
macroname_data
.
- Updated dependencies.
- Add
@icons
annotation. - Add
@preview
annotation for color palettes and font specimens. - Add syntax highlighting of code blocks.
- Initial release.
@macro
annotation and basic infrastructure.