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:
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: 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
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 { … }
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 »
Herman uses a number of SassDoc Extras: