Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Automatically generate a style guide from your stylesheets.
JavaScript CSS

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
examples
resources
shared
test-browser
test
.gitignore
.jshintrc
.npmignore
LICENSE
Makefile
README.md
cli.js
package.json
styledocco.js

README.md

 _______ __         __        _____
|     __|  |_.--.--|  |-----.|     \-----.----.----.-----.
|__     |   _|  |  |  |  -__||  --  | _  |  __|  __|  _  |
|_______|____|___  |__|_____||_____/_____|____|____|_____|
             |_____|

StyleDocco generates documentation and style guide documents from your stylesheets.

Stylesheet comments will be parsed through Markdown and displayed in a generated HTML document. You can write code examples prefixed with 4 spaces (or between ```, GitHub code fences) in your comments, and StyleDocco both renders the HTML and shows the code example.

An important philosophy of StyleDocco is to introduce as little custom syntax as possible, maintaining the stylesheet comments readable and useful even without StyleDocco.

The document is automatically split into new sections when it encounters a level 1 or 2 heading. Read more about the heading syntax in the Markdown guide. Only comments at the beginning of new lines are included, put some whitespace before a comment to exlude it from the style guide.

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

Installation

StyleDocco requires Node.js. After installing Node.js, run

npm install -g styledocco

or check out this repository.

StyleDocco is free software, released under the MIT license.

Usage

styledocco [options] [INPUT]

StyleDocco will automatically compile any SASS, SCSS, Less or Stylus files before they are applied to the page. You can also enter a custom preprocessor command if you want to pass custom parameters to the preprocessor.

If your project includes a README file, it will be used as the base for an index.html. StyleDocco will also add some default styles to your documentation, but they are easy to modify to make it fit with your project.

Options

  • --name, -n Name of the project (required)
  • --out, -o Output directory (default: "docs")
  • --resources, -s Directory with files to customize the documentation output. StyleDocco defaults will be used for any required file not found in this directory. (optional)
  • --preprocessor Custom preprocessor command. To disable preprocessing, use none. (optional) (ex: --preprocessor "scss --load-path=deps/")
  • --include Prepend specified CSS file to the documentation stylesheet. (optional) (ex: --include mysite.css)
  • --verbose Show log messages when generating the documentation. (default: false)
  • Directory containing the stylesheets to document.

Usage examples

Generate documentation for My Project in the docs folder, from the files in the css directory.

styledocco -n "My Project" css

Generate documentation for My Project in the mydocs folder, from source files in the styles folder. Use the Less binary in ~/bin/lessc.

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

Syntax examples

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

    <button class="btn primary">Primary</button> */
.btn.primary {
    background: blue;
    color: white;
}

Would display the description, a rendered button as well as the example HTML code. The CSS will be included in the style element of the document.

See the examples folder for more in-depth examples.

Acknowledgements

A lot of the heavy lifting in StyleDocco is done by the excellent Marked module by Christopher Jeffrey. The original Docco by Jeremy Ashkenas and Knyle Style Sheets have also been sources of inspiration for StyleDocco.

Something went wrong with that request. Please try again.