vitalstyles 1.1.4

Generate CSS/SASS/LESS documentation with previews using Markdown in comments.

# Vitalstyles

Makes it easy to document you LESS/SASS/CSS. You document your styles by inserting markdown with a few extensions to markup examples.


## Goals
Make it easier to document and develop styles.


## Features
- Document your styles with Markdown.
- Create live previews:
- Inline in the guide for simple examples.
- Covering the full width of the guide page for more complex examples.
- Rendered in a full width IFRAME for really complex examples. These examples can also be opened in a separate file.


## Install
```
$ pip install vitalstyles
```

## How it works
You write your css/less/sass like you have always done, but you add markdown in special comments:

``` css
/**
# Buttons

## .fancybutton
A fancy button

$$$
<button class="fancy-button">Click me</button>
$$$
*/
.fancy-button {
}
```

The ``vitalstyles-cli`` can be executed from the directory containing the file with these styles, and it will create a style guide in ``vitalstyles_styleguide/``. By default it will search the current directory recursively for ``*.less``, ``*.sass``, ``*.scss`` and ``*.css`` files.


## Configuration
You can configure vitalstyles through a ``vitalstyles.json`` file. This is the default setting file with defaults:

``` javascript
{
// Path to your CSS file relative to this settings file (or CWD if no settings file).
// You have to set this to get previews.
"preview_cssfile": null,

// The output directory relative to the settings file (or CWD if no settings file).
"outdir": "vitalstyles_styleguide",

// A list of files or directories to parse.
// Directories is searched recursively for ``.scss``,
// ``.sass``, ``.css`` and ``.less`` files.
"inpaths": [],

// User defined templates directory. You can override any
// templates in the ``vitalstyles/templates/`` directory
// (in the repo) by putting them in a directory and specifying
// the directory here. The path is relative to this settings file.
"template_dir": null,

// The title of the guide
"title": "Vitalstyles style guide",

// Include stock assets? This will add a directory named
// stock to your assets/ directory, and fill it with assets
// that you can use in your styleguide.
'include_stock_assets': false,

// A list of filesystem directories. The contents of these directories
// are copied into the assets sub-directory of the ``outdir``.
// The directory itself is not copied, so if you specify two directories
// containing the same file, the file from the last directory in the
// list will overwrite the first.
'asset_directories': []

}
```


## Embedded previews in the docs
If you want to get previews, you have to configure ``preview_cssfile`` in a ``vitalstyles.json``.


## Bundled stock images
We bundle a set of stock images. The bundled stock images are from https://unsplash.com/ and http://www.gratisography.com/.

To use the bundled stock images, you simply set the ``include_stock_assets`` setting to ``true``. This will copy the images from ``vitalstyles/sock_assets/stock/`` (in the sources of this library) into the ``assets/stock/`` subdirectory of the directory specified in the ``outdir`` setting.


## Adding assets (images, videos, etc)
If using the bundled stock images is not enough, you can include one or more asset directories using the ``asset_directories`` setting. You simply add the path to the directories you want to copy into the ``assets/`` subdirectory of the directory specified in the ``outdir`` setting.


## Specifying settings using Python or making a custom CLI
If configuring the styleguide using JSON is not enough, you can make a custom CLI script. This is fairly simple, and it is demonstrated in ``examples/custom_vitalstyles_cli.py``.


## Complete example
See the ``examples/`` directory in the source repo. To build the example, install Vitalstyles and GruntJS and run the following::

$ cd examples/
$ npm install
$ grunt

Then open ``vitalstyles_styleguide/index.html``.


## Markdown dialect
The Markdown dialect is more or less the same as the GitHub format, with one additional tag to markup examples.

The Markdown parser is [python-markdown](https://pythonhosted.org/Markdown/), with the following [extensions](https://pythonhosted.org/Markdown/extensions/index.html):

### Fenced code blocks
Makes it possible to use github markdown styled code blocks like:

``` javascript
function add(a, b) {
return a + b;
}
```

### Smart strong and smart emphasis
Prevents markdown from emphasizing words when you use ``_`` and ``__`` in the middle of a word.

### Definition Lists
Makes it possible to define definition lists with the following markup:

```
Option one
: This is not a very good option. You should consider
using _option two_.

Option two
: This is a really good option.
```

### Tables
Makes it possible to create tables with the following markup:

```
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
```


### SmartyPants
Converts ASCII dashes, quotes and ellipses to their HTML entity equivalents


### Sane lists
Renders lists in a saner manner than the original Markdown.