Ganam Style Guide

The command line tools for ganam.


Install with npm:

$ npm install ganam-cli -g

Remember the -g option.


The command line interface:

$ ganam -h

  Usage: ganam [options] <dir>


    -o, --out <dir>        Output to <dir> when passing files
    -t, --theme <name>     Specify the theme, default is github
    -u, --use <path>       Utilize the stylus plugin at <path>
    -I, --include <path>   Add <path> to lookup paths
    -c, --compress         Compress css output
    --import <file>        Import stylus <file>
    --include-css          Include regular css on @import
    -w, --watch            Watch file(s) for changes and re-compile
    -q, --quiet            Only show warn logs
    -v, --verbose          Show more logs
    -V, --version          Display the version
    -h, --help             Display this help menu

The style file structure:


Style Syntax

Find the syntax at: Ganam Parser

In CSS, it is something like:

1.1 Classy Buttons

Classy buttons is clickable form action buttons,
it is widely usage in forms.

:hover - button when hovered
:disabled - button when disabled
.disabled - the same as :disabled


    <button class="classy {{modifier}}">Button</button
    <a class="button-classy {{modifier}}">Button</a>

a.button-classy {
  color: #d64;
button.classy:hover {
  color: #000;

In stylus, you can use // as the comment leading, like:

// 1.1 Classy Buttons
// Classy buttons ....

There are five parts of a section:


The first line with a version number is the title, which is:

1.1 Classy Buttons


The lines below title and above modifiers, which is:

Classy buttons is clickable form action buttons,
it is widely usage in forms.


Modifiers are key value pairs to decorate the element:

:hover - button when hovered
:disabled - button when disabled
.disabled - the same as :disabled

The key is a class or a pseudo-class before -.

Modifiers are not required, the section may contain no modifiers.


Examples are code to be rendered. If the section has modifiers, the example code will be rendered (modifiers.length) times, and the variable {{modifier}} will be replaced every time.

Examples can be a path to a file:

Examples: ./code.html


Ganam-cli ships with a default theme. If you are not satisfied with it, you can write your own theme.

A theme folder is something like:

template.html     <- required
theme.js          <- optional
...               <- any other files will be copied to out directory


Template is powered by swig, you should learn some basic knowledge of swig markup.

Variables that can be used in template:


The guide variable is an object, which looks like:

    "order": 1,
    "name": "foo",
    "filename": "foo.styl",
    "filepath": "./foo.styl",
    "css": "button {.....}",
    "sections": [....]

sections is a list of section object, which looks like:

    "name": "1.1",
    "title": "Classy Buttons"
    "description": "Classy buttons is clickable form action buttons,\nit is widely usage in forms.",
    "modifiers": [
        {"name": ":hover", "description": "button when hovered"},
        {"name": ":disabled", "description": "button when disabled"},
        {"name": ".disabled", "description": "the same as :disabled"}
    "html": "<button class='classy {{modifier}}'>Button</button\n<a class='button-classy {{modifier}}'>Button</a>",
    "examples": [
        {"name": "", "code": "<button class='classy '>Button</button>......"},
        {"name": ":hover", "code": "<button class='classy pseudo-class-hover'>Button</button>......"},
        {"name": ":disabled", "code": "<button class='classy pseudo-class-disabled'>Button</button>......"},


Styleguides is a list of guide object ordered by order.


Readme is the content in

Ganam will search readme file in the style guide folder first, if not found, it will search readme file in the current working directory.


You can define some information in theme.js which can be used in template.html.

Take an example, your theme.js is: = 'ganam'

In your template.html, you can use the theme variable:


If you want to extend the filters, add in your theme.js:

exports.filters = {
    subtring: function(s, start, end) {
        return s.substring(start, end)

And then, you can use the substring filter in template.html:

{{ "ganam"|subtring(0, 2) }}


Jun 6, 2013 0.3.1

Jun 6, 2013 0.3.0

May 8, 2013 0.2.0

May 8, 2013 0.1.0

First preview release.