Sass source comment documentation generator
sassdocJs is a nodejs command-line (CLI) app that will parse jsDoc style comments* found in your
.scss source files, and use them to create a structured set of Html-based documentation. It's aim is to provide an easy way to catalog your growing library of sass mixins, functions, placeholders, etc, while complimenting whatever workflow, or Sass/Css/OOCSS standardization you may have adopted.
I've tried to keep things extensible: there's a default set of 'language definitions', such as
#id, but it's simple to construct custom definitions. A theme-able Html/Handlebars.js template is included. Finally, the parsed documentation result is saved as plain JSON, so you can easily work it into whatever front-end you fancy.
Document OOCSS-style naming conventions (BEM, SMACSS, custom)
Extensible with custom doc tags
Saved as JSON - use the included template or your own
// comments - see known issues below.
sassdocJs is built with nodeJs & can be installed with npm
$ npm install -g sassdocjs
$ git clone git://github.com/mattbieber/sassdocjs.git
To use sassdocJs, open up a shell and run the following command.
$ sassdocjs [path] [options]
With no arguments , sassdocJs will recursively search the current directory for Sass source files, and output generated documentation to
There's a fair amount of configuration switches, see below on how to supply them via a config file.
|-n, –name||name of the project|
|-u, –logo||logo file url to appear in documentation header|
|-d, –desc||project description|
|-v, –version||version of the documentation|
|-a, –auth||project author(s)|
|-b, –contrib||project contributors|
|-s, –status||project status|
|-x, –exclude||file pattern for exclusion|
|-i, –include||file pattern for inclusion|
|-o, –out||path to write generated docs to|
|-t, –templ||path to output template directory|
|-r, –recurse||recurse working directory for sass sources|
|-p, –prefix||categorize by prefix (e.g. |
|-c, –config||save .yml config file in working directory|
|-l, –log||toggle logging|
|-y, –verbose||logging verbosity|
|-m, –limit||set the allowed file parsing concurrency|
|-h, –help||show sassdocjs usage options|
You can simplify configuration by putting a YAML config file -
config.yml- at the root of your projects’ ource folder. See the one included in the example for file’s layout, or run
sassdocjs --configand fill out the created file.
When parsing files, sassdocJs pulls out comments using 'definitions' found in
lib/lang/defs. Definitions can be supplied for both in-comment tags, or for a keyword prefix character, as in
%, for Css Ids and Sass placeholders. The following are provided:
@moduleDefine a file as a module
@paramSass mixin/function argument
@returnsSass mixin/function return value
@usedinLocation(s) the documented item can be found
It’s fairly trivial to supply your own documentation tag definitions should you wish. Any
def_*.js file found by the parser will be included as a definition and have it's rules applied during validation. Definition files should implement
/*** language definition file for a Sass mixin*** @module lib/lang/defs/def_mixin*/var _sd = require'../../env/const'definitionBase = require'./_def'definitionBase;/*** @constuctor*//* implement base */definitionBasecallthistype_def: 'mixin'value: 64 //@name_position: 2context: _sdCONTEXTFIRST_CLASScanHaveValue: _sdVALIDATIONREQUIREDcanHaveDescription: _sdVALIDATIONOPTIONALcanHaveMeta: _sdVALIDATIONOPTIONAL;/* definitions must implement validate */;/* exports */moduleexports = ;
--prefix option, sassdocJs will parse and group your files according to word prefix entries placed in
lib/lang/prefix.js. I've included SMACSS-ish entries, but anything can be supplied.
moduleexports =// smacss'm-' : 'module''l-' : 'layout''s-' : 'state''is-' : 'state';
The prefixed grouping is called 'category' in the docs
A few resources regarding OOCSS-style naming:
You can provide an
@usedin entry in your comment block with a comma-separated value of locations (e.g. header, shopping cart, home page). sassdocJs will include that as a grouping option in the generated docs.
The use location grouping is called 'used' in the docs
The included Handlebars template is pretty straight-forward. It uses the generated
sassdocjs-data.js as it's data source. I've included some rudimentary themeing ability which you can find in the
./Sass directory. See one of the existing theme files for reference.
If you do customize, you'll want to run
$ grunt build in the template directory to compile the Sass and move it to the build folder.
You can run the included test with make or grunt:
$make / $grunt test
Additional fixtures can be put in
For eample useage, please see the commented Sass source and Yaml config file in
*I went with jsDoc-style comments for the simple reason that I prefer them to the Sass
// variety. The (obvious) drawback is that the Sass compiler won't strip these out upon compilation. I've got some ideas in mind for this on the roadmap, but please contribute if you wish. I also decided to eschew support for the older syntax style (.sass). Feel free to fork the repo and add it.
This is 0.1.0 code - please get in touch with any issues you encounter.
Note: This has been minimally tested in Windows
Following is what's planned.
- Add support for standard Sass
- Ability to strip sassdocJs comment blocks
//* */on save so they don't end up in the pre-compiled Sass files.
- Move name prefixing setting to config file.
Licensed under the MIT License (MIT)