An Odd SassDoc theme.
Latest commit d16e035 Nov 5, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Fix coveralls reporting. Nov 5, 2018
assets Upgrade highlight.js Nov 5, 2018
dist build Nov 5, 2018
docs Upgrade deps. Nov 5, 2018
fonts/rockingham Initial annotation docs. Nov 16, 2017
lib Improve error message when reading external files [closes #311]. Aug 23, 2018
scss Upgrade deps. Nov 5, 2018
templates Upgrade deps (notably webpack4). Mar 28, 2018
test Upgrade deps. Nov 5, 2018
.babelrc.js Upgrade deps (notably webpack4). Mar 28, 2018
.browserslistrc Upgrade deps; update browserslist. Apr 24, 2018
.eslintignore Add Webpack, Babel Nov 28, 2017
.eslintrc.yml lint Nov 28, 2017
.gitignore Upgrade deps (notably webpack4). Mar 28, 2018
.npmignore Upgrade deps (notably webpack4). Mar 28, 2018
.nycrc review cleanup Dec 4, 2017
.prettierrc Update dependencies. Sep 14, 2017
.sass-lint.yml Upgrade deps (notably webpack4). Mar 28, 2018
CHANGELOG.md Improve error message when reading external files [closes #311]. Aug 23, 2018
CONFIGURATION.md Allow passing through Sass outputStyle. Mar 27, 2018
CONTRIBUTING.md Document gulp4 requirements Jan 11, 2018
LICENSE Add MIT license. Nov 28, 2015
README.md Remove node-sass from peerDependencies (only required if using `@example Apr 13, 2018
appveyor.yml Fix bugs in customCSS url rewriting. (#269) Mar 27, 2018
gulpfile.js Run prettier on test sass files. Mar 29, 2018
index.js Clean up new @sizes/@ratios/@Colors annotations; Do not gitignore fil… Nov 28, 2017
karma.conf.js Upgrade deps (notably webpack4). Mar 28, 2018
package.json chore(package): update webpack to version 4.25.1 Nov 5, 2018
postcss.config.js Add Webpack, Babel Nov 28, 2017
sass-json-loader.js Add Webpack, Babel Nov 28, 2017
sassdoc-webpack-plugin.js Rewrite internal sassdoc-webpack-plugin. Mar 29, 2018
webpack.config.js Upgrade deps. Nov 5, 2018
yarn.lock chore(package): update lockfile yarn.lock Nov 5, 2018

README.md

Herman [a SassDoc theme]

CircleCI AppVeyor Coverage Status Greenkeeper badge

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: node-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 node-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: