Styleguide Generator for UI Components.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
template
test
.gitignore
LICENSE
README.md
package.json

README.md

ui-docs

Styleguide Generator for UI Components.

ui-docs is still a WORK IN PROGRESS.

Features

  • Dynamic @directives
  • @state and @modifier 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 (or flatten a tree into a single page)
  • Works with any CSS-preprocessing language or with CSS directly
  • Easily extendible. Custom translators for each @directive.

Installation

$ npm install ui-docs

Usage

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

Or if you are using Grunt, there is a ui-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
 *
 * @snippet
 * <i class="Ico {{classes}}"></i>
 *
 * @id 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
 *
 * @theme dark
 * @snippet
 * <a class="button {{classes}}">Button</a>
 *
 * @theme light
 * @snippet
 * <button class="button {{classes}}">Button</button>
 *
 * @theme dark
 * @snippet
 * <a class="button {{classes}}">
 *     {{use 'components.icon Ico--edit'}}
 *     <span>Button</span>
 * </a>
 *
 * @id components.button
 */
/**
 * Button Group
 * Lorem ipsum Non do id tempor {{link_to 'components.button'}} 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
 *
 * @snippet
 * <div class="BtnGroup {{classes}}">
 *     {{#repeat 4}}
 *         {{use 'components.button'}}
 *     {{/repeat}}
 * </div>
 *
 * @id components.buttonGroup
 */

Options

Name Type Default Description
title String 'ui-docs' Title used for the Styleguide.
docsPath String 'docs/styleguide' Path where generated Styleguide will be located.
docsAssetsPath String 'assets/' Path where your project assets are copied to. Relative to docsPath.
docsUIDocsAssetsPath String 'css-docs/' Path where ui-docs assets are copied to. Relative to docsAssetsPath.
templatePath String path.join(__dirname, '../template/') Path to the theme folder used to generate the docs.
rawAssetsDir String 'assets/' Path to your project raw assets.
extrasPath String 'docs/extras/' Path to directory where extra files (useful to load extra html/js/css for demo purposes) are located.
js
js.rawDir String 'js/' Path to raw javascript files. Relative to rawAssetsDir.
js.validExtensions Array ['.js', '.coffe'] Valid extensions for javascript files.
js.ignore Array ['**/vendor/**', '**/vendor-setup/**'] Ignore files from being parsed. Using multimatch
css
css.rawDir String 'css/' Path to raw CSS files. Relative to rawAssetsDir.
css.validExtensions Array ['.scss', '.css', '.sass', '.styl', '.less'] Valid extensions for CSS files.
css.ignore Array ['**/bourbon/**'] Ignore files from being parsed. Using multimatch
css.builtFilePaths Array [assets/css/built.css] Paths where final build/compiled CSS files will be copied to. To use in the styleguide.

Doc block variables (for templating)

  • title (first line of description)
  • description
  • name (one word, from styleguide)
  • modifier
    • classes
    • name
    • description
  • state
    • classes
    • name
    • description
  • usage
  • snippet
  • snippet_highlighted
  • embeds
  • flatten
  • nopreview
  • styleguide (components.button)
  • theme (light/dark/gray)
  • line
  • filePath
  • absoluteFilePath
  • treePath (components.childs.button)

Development

Checkout the project and go to:

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

Compile example sass

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

Generate docs

$ node ui-docs.js

TO-DO

  • @extends and @depends directives
  • think in a way to have different markup for modifiers of the same CSS object
  • helper for lorem ipsum
  • refactor
  • error reporting
  • write tests, a lot of 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)