If it's not documented, it doesn't exist. Documentation should become the default -- an integrated part of the development process.
At OddBird, we wanted better tools for documenting the entire front end of a project -- from brand guidelines to UX patterns and code APIs:
- Documenting the intersection of languages and styles
- Written directly in the code, and integrated with code architecture
- Automated for a document that grows and changes along with the life of your project
Herman is built as an extension to SassDoc, and supports all their core functionality with additional support for font specimens, color palettes, sizes and ratios, SVG icons, compiled languages, Nunjucks/Jinja macros, HTML previews, and more.
npm install sassdoc sassdoc-theme-herman
Note: A Sass implementation (
is required to use Herman
to display samples of Sass/Scss code.
If it's not already installed in your project,
install it along with Herman:
npm install node-sass
See the SassDoc documentation
to run SassDoc via various build tools.
herman as the theme
in your SassDoc options:
sassdoc <src> --theme herman
all SassDoc/Herman annotations are written as Sass comments
/// to differentiate documentation
from other developer comments (
// This comment will be ignored by Herman/// This comment will be rendered in the documentation
Annotation comments can be free-floating, or attached to a particular Sass/CSS object -- such as a variable, mixin, function, or selector block. Note that while SassDoc allows annotation comments to be separated from the documented code by newlines, Herman considers documentation to be free-floating "prose" if it is separated from documented code by one or more newlines.
/// this is a free-floating comment/// this comment is attached to the following mixin code-block
In addition to the core SassDoc annotations,
@icons annotation allows you to
display SVG icons from a given folder,
and we extend the core
to display compiled Sass/Nunjucks output
and render sample components.
We also provide a
for displaying font-specimens,
for displaying color-palettes,
text and spacing sizes, and modular ratios.
Herman uses a number of SassDoc Extras: