Using custom templates

Thiago de Mello Bueno edited this page May 4, 2018 · 5 revisions

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.