/css-docs

CSS Styleguide Generator focused on CSS Modular Architectures

Primary LanguageJavaScript

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)