silvermine-styleguide

1.0.0 • Public • Published

grunt-styleguide

This grunt plugin is focused towards building a static file HMTL/CSS/JS styleguide. In reality, though, it's just a static site generator. This means, that you can use it to compile almost any kind of static site you can imagine.

Sample Configuration

grunt.initConfig({
    /**
     * Style Guide Compiler
     */
    styleguide: {
        basic: {
            // Compiler configuration:

            // Paths relative to your Gruntfile
            sourceDir: "./style-guide/src",
            outputDir: "./style-guide/dist",

            // Paths relative to sourceDir
            template: "index.html",
            partials: "tests/**/*.html",
            guideCSS: "main.scss",
            guideJS: "main.js",
            favicon: "favicon.ico",

            // Any other arbitrary keys you want can be included here. They
            // are made available to the template. For example you might include:

            // URLs to CSS files to include
            coreCSS: [
                '/assets/example-1.css',
                '/assets/example-2.css'
            ],

            // URLs to Javascript files to include
            coreJS: [
                '/assets/example-1.js',
                '/assets/example-2.js'
            ],

            // A title for my styleguide
            title: "My Fancy Style Guide"
        }
    }
});

grunt.loadNpmTasks('silvermine-styleguide');

Configuration Reference

Option Description
sourceDir This is the path (relative to your Gruntfile) that defines where your site's source files are placed.
outputDir This is the path (relative to your Gruntfile) that defines where the compiled output will be placed.
template This is the name of the Nunjucks HTML template to compile on the server. Generally this is your index.html document.
partials This is a glob pattern of Nunjucks HTML templates that should be precompiled into a client-side javascript file.
compiledPartialsName Filename to save precompiled templates into. Defaults to templates.js
guideCSS This is the path (relative to the sourceDir) of the CSS or Sass for your site. It will be run through the Sass compiler to be compiled into CSS in the outputDir .
guideJS This is the path (relative to the sourceDir) of the Javascript for your site. It will be run through the Browserify compiler and placed in the outputDir.
favicon Path (relative to the sourceDir) of your site's favicon.

Example Templates

During compilation, the partials directory will be analyzed. Metadata and path information will be extracted and made available to the server-side template while rendering. Below are some example templates.

Client Side Template

---
title: Form Buttons
description: A sample selection of HTML button elements
---
{% extends "base.html" %}

{% block content %}
   <form>
     <fieldset>
       <p><input type="button" value="Input type button"></p>
       <p><input type="reset" value="Input type reset"></p>
       <p><input type="submit" value="Input type submit"></p>
       <p><input type="submit" value="Input type submit disabled" disabled></p>
       <p><button type="button">Button type button</button></p>
       <p><button type="reset">Button type reset</button></p>
       <p><button type="submit">Button type submit</button></p>
       <p><button type="button" disabled>Button type button disabled</button></p>
       <p><button>Button</button></p>
     </fieldset>
   </form>
{% endblock %}

Client side template optionally begin with YAML formatted front-matter. This can be used to describe the using any arbitrary keys desired. This YAML will be parsed at pre-compile time and made available to the server side template.

Server Side Template

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>{{ title }}</title>
    </head>

    {% macro selector(tree) %}
        <ul>
            {% for group in tree.subgroups %}
                <li>
                    <p>{{ group.name }}</p>
                    {{ selector(group) }}
                </li>
            {% endfor %}

            {% for partial in tree.partials %}
                <li>
                    <p data-path="{{ partial.path }}">{{ partial.name }}</p>
                </li>
            {% endfor %}
        </ul>
    {% endmacro %}

    <body>
        <div id="metadata" style="display:none;">{{ metadata }}</div>

        <ul>
            <li>
                <p>Partials</p>
                {{ selector(partials) }}
            </li>
        </ul>

        <script type="text/javascript" src="templates.js"></script>
        <script type="text/javascript" src="main.js"></script>
    </body>
</html>

Package Sidebar

Install

npm i silvermine-styleguide

Weekly Downloads

2

Version

1.0.0

License

MIT

Last publish

Collaborators

  • crgwbr