StyleDocco generates documentation and style guide documents from your stylesheets.

Stylesheet comments will be parsed throughMarkdown and displayed in a generated HTML document. You can write HTML code prefixed with 4 spaces or betweencode fences (```) in your comments, and StyleDocco shows a preview with the styles applied, and displays the example HTML code.

The previews are rendered in resizable iframes to make it easy to demonstrate responsive designs at different viewport sizes.

Suggestions, feature requests and bug reports are very welcome, either atGitHub or on Twitter (@jacobrask).

Installation

StyleDocco requiresNode.js. After installing Node.js, runnpm install -fg styledocco or clone this repository.

StyleDocco is free software, released under theMIT license.

Stylesheet

The following is the code you would write in your stylesheet, and theOutput is what you would see in the documentation.

/* Provides extra visual weight and identifies the primary action in a set of buttons.    <button>Primary</button>*/.btn.primary {    background: steelblue;    color: snow;    border: 2px outset steelblue;}

Output

Provides extra visual weight and identifies the primary action in a set of buttons.

For more in-depth examples, thedocs file is the documentation of the default StyleDocco CSS file, and anadditional example was generated from a modified file of the Twitter Bootstrap project.

styledocco [options] [INPUT]

Options

• --name,-n Name of the project(required)
• --out,-o Output directory(default: "docs")
• --preprocessor Custom preprocessor command.(optional) (ex:--preprocessor "scss --load-path=deps/")
• --include Include specified CSS and/or JavaScript files in the previews.(optional) (ex:--include mysite.css --include app.js)
• --verbose Show log messages when generating the documentation.(default: false)
• --no-minify Do not minify the code.(default: false)
• Directory containing the stylesheets to document.

Usage examples

Generate documentation forMy Project in thedocs folder, from the files in thecss directory.

styledocco -n "My Project" css

Generate documentation forMy Project in themydocs folder, from source files in thestyles folder. Use the Less binary in~/bin/lessc.

styledocco -n "My Project" -o mydocs -s mydocs --preprocessor "~/bin/lessc" styles

Tips and tricks

• StyleDocco will automatically compile any SASS, SCSS, Less or Stylus files before they are applied to the page
• If your project includes a README.md file, it will be used as the base for an index.html
• If you don't specify a custom name, StyleDocco will use the name from a package.json file if it finds one
• Put some whitespace before a comment block to exclude it from the documentation
• Level 1 headings will automatically create a new section in the documentation
• Add:hover,:focus, etc as class names in example code and the pseudo class styles will be applied in the preview

Acknowledgements

A lot of the heavy lifting in StyleDocco is done by the excellentMarked module by Christopher Jeffrey. The originalDocco by Jeremy Ashkenas andKnyle Style Sheets have also been sources of inspiration for StyleDocco.

0.6.6

January 28, 2014

• Fix failure to render iframes in new versions of Chrome (#100)
• Make it an option to minify the code (#106)

0.6.5

November 17, 2013

• Fix failure to install on some systems (#94)

0.6.4

October 07, 2013

• Large preprocessor outputs hit the maxBuffer limit (#87)
• Relative image path is no longer added to data: URLs (#88)
• Replace path.exists with fs.exists (#92)
• Can now use a backslash to separate directories on Windows (#95)
• HTTP URLs in paths now behave correctly (#97)

0.6.3

July 09, 2013

• Do not add relative paths to data URLs

0.6.2

June 30, 2013

• Find assets recursively in Windows
• Fail gracefully on no files error
• Relative url() paths are now preserved

0.6.1

August 20, 2012

• Mute all preprocessor errors unless using verbose option
• Don't try to preprocess SASS partials
• Design tweaks

0.6.0

August 15, 2012

• Remove custom resources option, as client side scripts/styles are vital to the functionality
• Editable, auto-updating code examples
• Documentation-wide search
• Page specific Table of Contents

0.5.0

July 23, 2012

• Render previews in sandboxed iframes
• Resizing of iframes for responsive debugging
• All processed CSS is included in all previews
• Allow custom JavaScript and CSS files to be included in previews
• Updated design with topbar instead of sidebar and new colors