CSS is getting more and more complex. Sass solves a lot of CSS issues, but at the same time is likely to bring some extra complexity to the game. Documenting Sass code is as vital as documenting regular CSS, if not more so. It's not only important for the next developer, but so you still understand your own code six months from now.
SassDoc is to Sass what JSDoc is to JavaScript. The idea is simple: you document your code by writing inline comments in a specific way, run some short command line code, then some beautiful documentation is magically generated. Isn’t that nice?
Pascal Duez, Valérian Galliat, Fabrice Weinberg and I have been working on this project and we could not be happier with what we have come up with so far. One of our top priorities is to keep SassDoc scalable so it can be used on basically any Sass project. Small site? No problem. Huge code base? We got you covered.
And if you're not happy with what we provide out of the box, worry not – SassDoc is fully extendable and themable. The Guardian Style Sheets (Guss), Bourbon and Neat have already jumped in and moved their documentation to SassDoc, so what are you waiting for?
SassDoc-powered documentation takes place over the course of several stages – most of which are invisible for the end user (you):
- The parser goes through all the files from your source folder to grab SassDoc-compliant comments
- The parser builds a data tree
- At the same time, the destination folder gets
(re)generated
- If asked to, the data tree gets enhanced to provide additional features (cross-references between items, Markdown descriptions, ordering and so on)
- The data structure gets handed over to the theme
- The theme displays it in the destination folder
- You are as happy as a unicorn
Getting started with SassDoc is as easy as writing comments in your Sass files. Now, SassDoc is able to document functions, mixins, variables and placeholders either with inline comments
( /// ) or C-style comments ( /** */ ).
For each ‘item’ you want to document, write some comments in a JSDoc fashion. For instance:
/// Baseline for all margins and gaps on the site
/// @group configuration
/// @access public
/// @type Number
$baseline: 1.5em;
/// Centre a block to make it a container
/// @group helpers
/// @param {Number} $max-width - Max width for the container
/// @require $baseline
/// @output 'max-width', 'margin' and 'width'
@mixin center($max-width: 1170px) {
max-width: $max-width;
margin: 0 auto $baseline;
width: 100%;
}
Once you have written such comments for every item you want to document, you only have to run SassDoc on your code base. First, install SassDoc:
npm install sassdoc -g
Then run it on your code (input folder) and specify where the documentation should be generated (output folder):
sassdoc /assets/scss docs
You can also pass a number of options – including a path to a configuration file (JSON or YAML) with
--config, so you can customise the view. All available options can be found on the official documentation.
Themes
SassDoc provides a default theme, ready to be used out of the box. It mostly consists of a sidebar that can be extended or collapsed, and sits alongside a main content area where all the items are displayed.
Because this theme is likely to be the one that's most commonly used, we added a lot of extra features, including:
- A client-side search engine
- A 'view source' link for each item, heading to an online repository
- An expandable sidebar to manage groups
- The ability to define custom names for groups
- The ability to display only public/private items, and to hide and show aliases
- The ability to display the content of each item (functions, mixins, placeholders and so on)
- The ability to define a custom favicon
- The ability to display information about your project through a JSON file (for instance package.json)
Theming engine
We are well aware that the default theme for SassDoc may not please or suit everybody. That's why we made SassDoc fully themable, thanks to a powerful little theming engine we built specially for SassDoc called Themeleon.
Building a theme takes a bit of time but should be quite easy, especially if you use our Yeoman theme generator. In this case it's all about answering a couple of questions, adding a little of your favourite template engine (Swig, Jade, Mustache, Nunjucks ...) and putting some CSS on top.
If you want your theme to be a bit more advanced, SassDoc also provides a collection of tools that can be imported and used by any theme. Want descriptions to be written in Markdown? We got it. You'd like to provide helpful aliases to group names? Possible with the extra tools. You can even define your own annotations. Also, in order to help you when you’re building your own theme, we've created a 'blank' one that comes complete with a lot of comments explaining what to do.
Third-party integration
Once your theme is ready, you could package it up for the world through npm. Using the sassdoc-theme-* name pattern means other developers can use it for their SassDoc-powered documentations by simply passing the --theme option from CLI (or theme from configuration file). The Neat and Vulcan frameworks have already built their own themes that you can use.
If you want to include SassDoc in your deployment process, we've built a Grunt, Gulp and Broccoli plugin. Alternatively, you could use the raw data or our Node API – whatever floats your boat.
For instance, Grunting SassDoc would likely look like this:
grunt.initConfig({
'sassdoc': {
'default': {
'src': 'path/to/sass',
'dest': 'path/to/docs'
}
}
});
SassDoc intends to bridge the gap between APIs, frameworks, libraries, makers and developers by generating simple yet powerful documentations. In the future, we might be able to document more things, inluding CSS selectors, @import rules or even BEM methodology.
If you happen to build a theme, need any help or just want to share the love, feel free to get in touch with @SassDoc_ on Twitter.
Words: Hugo Giraudel
Hugo Giraudel is a designer at
Teknolog.io. This article first appeared in net magazine.
Like this? Read these!
