Skip to main content

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

Project description

# 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vitalstyles-1.1.4.tar.gz (432.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page