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.
Requirements
Should work with any fairly new version of Python. Tested on Python 2.7 and Python 3.4.
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:
/**
# 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:
{
// 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, with the following extensions:
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.