YM Styleguide

This script will pull out anything that looks like this:

---
title: {title of styling block}
description: |    # Note the pipe character here.
    {brief description of styling block. parsed in markdown.}
elements:
    - {list of}
    - {elements used}
modifiers:
    - {list of}
    - {available modifiers}
parameters:
    - {list of}
    - {input parameters}
    - {for mixins}
returns:
    - {list of}
    - {output parameters}
    - {for mixins}
example: |     # Note the pipe character here as well.
    <div>
        {An HTML example}
    </div>
---

...and produce a single HTML styleguide document. Only the title field is required.

Elements, modifiers, parameters, and returns can all accept multilevel lists. In the generated style guide, the title of these fields will have a class of sg-field.

Examples will both render directly as well as provide a summary and details toggle to view the code source within the generated styleguide. They are wrapped in a div with a class of sg-example.

It doesn't care if you are using CSS, Sass, SCSS, Less, Stylus... it has no knowledge of such things.

You also need an outline.json in your stylesheets directory to tell it how to organize the blocks into the styleguide document. It looks like this:

{ "outline": [
    "Metrics",
    "Global Utilities", [
        "Clearfix",
        "Display Type Helpers",
        "Pull and Push Helpers",
    ],
    "Typography", [
        "Font Sizes",
        "Width Limiting",
        "Headings, Subheadings, and Header Groups",
        "Paragraphs", [
            "Leading Paragraphs"
        ]
    ]
] }

The title must be identical to the outline to match up. If you use a title in the outline that doesn't exist as a component, it will just display the title. It will warn you however if not all blocks have been used by the outline.

Then with the NPM:

var yms = require('ym-styleguide');
yms.build('/stylesheets', function(html) {
    // do something with `html`
});