Pixu [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

Pixu 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-pixu

Note: node-sass is required to use Pixu to display samples of Sass/Scss code. If it's not already installed in your project, install it along with Pixu:

npm install node-sass

See the SassDoc documentation to run SassDoc via various build tools. Specify pixu as the theme in your SassDoc options:

sassdoc <src> --theme pixu

SassDoc Comments

Currently, all SassDoc/Pixu annotations are written as Sass comments starting with /// to differentiate documentation from other developer comments (//).

// This comment will be ignored by Pixu
/// 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, Pixu 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 { … }

Pixu 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

Pixu uses a number of SassDoc Extras:

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