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)