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 [email protected]:vieron/ui-docs.git
$ cd ui-docs/example
$ git clone [email protected]: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)