@knapsack/scss-utils

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.

---Miriam Suzanne

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:

• Description
• Display
• GroupName
• ShortcutIcon
• Sort
• ResolveVariables