ui-docs v0.0.1
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)