Herman [a SassDoc theme]
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.
Getting Started
npm install sassdoc sassdoc-theme-herman
Note: Dart Sass (sass)
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 sass
See the SassDoc documentation
to run SassDoc via various build tools.
Specify herman as the theme
in your SassDoc options:
sassdoc <src> --theme herman
SassDoc Comments
Currently,
all SassDoc/Herman annotations are written as Sass comments
starting with /// 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
@mixin sample-object { … }
Herman Annotations
In addition to the core SassDoc annotations,
our @icons annotation allows you to
display SVG icons from a given folder,
and we extend the core @example annotation
to display compiled Sass/Nunjucks output
and render sample components.
We also provide a @font annotation
for displaying font-specimens,
and @colors, @sizes, and @ratios annotations
for displaying color-palettes,
text and spacing sizes, and modular ratios.
See the full documentation for details »
SassDoc Extras
Herman uses a number of SassDoc Extras: