Using custom templates

Unlike the original Ruby library, kss-node comes bundled with a command-line tool so you can generate a static style guide out of the box.

After installation, you will be able to type the following into your terminal and have a working style guide for your project:

kss-node --source [Stylesheet Directory] --destination [Output Directory] --css [URL to CSS File]

Chances are things aren't quite right – for one, you'll want to modify the core template to match your site's markup, much like Github did for its own styleguide. So, you can create a new template to work on like so:

kss-node --clone [New Template Directory]
cd [New Template Directory]

if you want to clone a builder other than the default builder, then specify it using --builder kss --clone --builder=node_modules/kss/builder/twig/ In this new directory you'll find a file called index.html. This is the main template file, used to generate all of your style guide pages. There's also a directory called public, which is copied over to your generated style guide and helpful for including external assets such as images or JavaScript files. Play around with these, and once you've made your changes, you can just use the --builder flag to substitute the default template with your own:

kss-node --source [Stylesheet Directory] --destination [Output Directory] --css [URL to CSS File] --builder [Template Directory]

Handlebars Helpers

Thanks to Handlebars, it's quick to get your own templates together. For example, here's what you could use to create a navigation bar for your styleguide:

<ul>
    {{#eachRoot}}
        <li><a href="section-{{reference}}.html">{{reference}}: {{header}}</a></li>
    {{/eachRoot}}
</ul>

To loop over each of the sections under this page and output their header/description, you could use:

{{#eachSection rootNumber}}
    <h1>{{header}}</h1>
    {{html description}}
{{/eachSection}}

Put simply, {{#eachSection rootNumber}} will "loop" over each section on the current page. You could reference a specific section by using {{#section "1.1"}} too. Inside the section loop, you can use the following (to name a few):

• {{header}} - The title of this section.
• {{html description}} - The Markdown-formatted description for this section.
• {{html markup}} - The markup example for this section, as HTML.
• {{markup}} - The escaped markup example for this section.
• {{reference}} - The reference number for this section.
• {{#eachModifier}} - Another loop, for each modifier in this section.

Going deeper, you could output the description and examples for each modifier like so:

{{#eachSection rootNumber}}
    <h1>{{header}}</h1>
    {{html description}}

    {{#eachModifier}}
        <div class="modifier">
            <h1>{{name}}</h1>
            {{html description}}

            <div class="example">
                {{modifierMarkup}}
            </div>
        </div>
    {{/eachModifier}}
{{/eachSection}}

Check out the handlebars template for a complete example in action.