Awesome

THIS REPO HAS BEEN MOVED TO vieron/ui-docs

css-docs

CSS Styleguide Generator focused on CSS Modular Architectures and written in Javascript.

css-docs is a WORK IN PROGRESS but you can see a demo here

Features

Dynamic @directives
@state and @modifier directives
@extends and @depends directives
Supports Custom templates
Focused on Modular CSS Architectures
Use Markdown in descriptions
Write less markup using Handlebars helpers
Give some hierarchy to your CSS using dot paths
One single HTML page for each component
Works with any CSS-preprocessing language or with CSS directly
Easily extendible. Custom translators for each @directive.

Installation

$ npm install css-docs

Usage

css-docs is a node package, you can write a small .js file and run it from the command line. See example/css-docs.js

Or if you are using Grunt, there is a css-docs grunt plugin here.

Example

/**
 * Icon
 * Lorem ipsum Non do id tempor laboris do ut veniam in sint fugiat fugiat
 * adipisicing elit Excepteur.
 *
 * @modifier .Ico-edit Lorem ipsum dolor sit amet
 * @modifier .Ico-settings Lorem ipsum dolor sit amet
 *
 * @markup
 * <i class="Ico {{classes}}"></i>
 *
 * @styleguide components.icon
 */

/**
 * Button
 * Lorem ipsum Non do id tempor laboris do ut veniam in sint fugiat fugiat
 * adipisicing elit Excepteur.
 *
 * @state :hover
 * @state .js-isDisabled Lorem ipsum dolor sit amet
 *
 * @modifier .btn--success Lorem ipsum dolor sit amet
 * @modifier .btn--cancel Lorem ipsum dolor sit amet
 *
 * @depends component.icon
 * @depends component.foo
 *
 * @extends component.link
 *
 * @markup
 * <a class="button {{classes}}">Button</a>
 *
 * @markup
 * <button class="button {{classes}}">Button</button>
 *
 * @markup
 * <a class="button {{classes}}">
 *     {{use 'components.icon Ico--edit'}}
 *     <span>Button</span>
 * </a>
 *
 * @styleguide components.button
 */

/**
 * Button Group
 * Lorem ipsum Non do id tempor laboris do ut veniam in sint fugiat fugiat
 * adipisicing elit Excepteur.
 *
 * @modifier .BtnGroup--compact Lorem ipsum dolor sit amet
 * @modifier .BtnGroup--fullWidth Lorem ipsum dolor sit amet
 *
 * @depends component.button
 *
 * @markup
 * <div class="BtnGroup {{classes}}">
 *     {{#repeat 4}}
 *         {{use 'components.button'}}
 *     {{/repeat}}
 * </div>
 *
 * @styleguide components.buttonGroup
 */

Options

Name	Type	Default	Description
title	`String`	`'css-docs'`	Title used in the generated Docs
logo	`String/Boolean`	`false`	If it's a String is used as src attribute of an image tag. It replaces title.
docsPath	`String`	`'docs/'`	Path where generated Docs are placed
docsAssetsPath	`String`	`'docs/assets/css-docs/'`	Path where theme assets are copied to use in generated Docs
styleDir	`String`	`'assets/sass/'`	Path where your project CSS/sass/less files are located.
styleFileExt	`Array`	`['.scss', '.css', '.sass', '.styl', '.less']`	Valid file extensions to search for comments. Used by `styleDir`.
ignore	`Array`	`['/bourbon/']`	Ignore files to be parsed. Uses multimatch
builtAssetsDir	`String`	`'assets/'`	Your project assets (images, fonts, javascripts). That are copied to `docsPath + '/assets'`.
builtCSSPath	`String`	`'css/built.css'`	Path to the compiled, concatenated, mininified... CSS. Relative to `builtAssetsDir`.

Doc block variables (for templating)

title (first line of description)
description
name (one word, from styleguide)
modifier
- classes
- name
- description
state
- classes
- name
- description
depends
depends_html
extends
depends_html
usage
markup
markup_highlighted
styleguide (components.button)
line
filePath (sass/ducksboard.scss)
absoluteFilePath (/Users/vieron/code/projects/css-docs/example/sass/ducksboard.scss)
treePath (components.childs.button)

Development

Checkout the project and go to:

$ git clone git@github.com:vieron/css-docs.git
$ cd css-docs/example
$ git clone git@github.com:vieron/css-docs.git docs
$ cd docs
$ git checkout gh-pages

Compile example sass

$ cd example
$ sass --watch assets/sass/ducksboard.scss:assets/css/built.css

Generate docs

$ node css-docs.js

TO-DO

refactor
error reporting
write tests
@experimental and @deprecated directive
@index directive to render TOC
option to generate a JSON representation instead of generate HTML docs
copy code snippet (zeroclipboard)