Nimble Polyglot Microcosm
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    styleguidejspublic

    styleguide.js

    Generate a styleguide from your CSS, by adding YAML data in the comments. It generates a self-contained html file. Works great for component based CSS.

    View the example generated styleguide

    Install

    Styleguide.js runs on node. Just run npm install styleguidejs.

    How to use

    You can add comments to your css. When it has three asterisks, it will be parsed as YAML data. The properties title, section and example are required by the default template, but when using your own template you can add all the things you would like. (like browser support, media query etc...). Example can be a string or an array.

    body {
      font: 16px Verdana;
    }
     
    /***
      title: Square buttons
      section: Buttons
      description: Very pretty square buttons
      example: |
        <a href="" class="btn btn-small">button</a>
        <a href="" class="btn btn-medium">button</a>
        <a href="" class="btn btn-large">button</a>
    ***/
     
    .btn{
      display: inline-block;
      padding: .3em .6em;
      color: white;
      text-decoration: none;
      text-transform: uppercase;
      background-color: darkslateblue;
    }
    .btn:hover{
      background-color: #38306E;
    }
    .btn-small{
      font-size: .8em;
    }
    .btn-medium{
      font-size: 1em;
    }
    .btn-large{
      font-size: 1.3em;
    }
     
     
    /***
      title: Round buttons
      section: Buttons
      description: Very pretty rounded buttons
      example: |
        <a href="" class="btn btn-small btn-round">button</a>
        <a href="" class="btn btn-medium btn-round">button</a>
        <a href="" class="btn btn-large btn-round">button</a>
    ***/
     
    .btn-round{
      border-radius: 20px;
    }
     
     
    /***
      title: Links
      section: Buttons
      id: btn-link
      description: Very pretty rounded buttons
      example:
        <a href="" class="btn-link">button</a>
    ***/
     
    .btn-link{
      background: none;
      color: darkslateblue;
    }
    .btn-link:hover{
      text-decoration: none;
    }
     
    /***
      title: Includes
      section: Includes
      description: Include example code from other items. You can refer to any attribute(set), like 'id'
      example: |
        <div class="btn-group">
            <include title="Links" section="Buttons">
            <include title="Links" section="Buttons">
            <include id="btn-link">
        </div>
    ***/
    .btn-group .btn-link {
        background: green;
    }
     
    var StyleGuide = require('styleguidejs');
    sg = new StyleGuide();
    sg.addFile("mystyle.css");
    sg.render({
        extraCss: ['append-custom.css'],
        extraJs: ['jquery.js'],
        outputFile: "test/index.html"
    });

    See /test for a demo implementation, and demo export file (index.html). You can add your own properties in the Yaml data, and parse them in your custom template.

    Customize look and feel

    Feel free to use your own look and feel. Include your own css, js or use your own Jade-template.

    var StyleGuide = require('styleguidejs');
    var sg = new StyleGuide();
    sg.addFile("mystyle.css");
    sg.render({
        templateCss: "styleguide/style.css",
        templateJs: "styleguide/script.js",
        template: "styleguide/template.jade",
        beautifyHtml: {
          preserve_newlines: false // see https://www.npmjs.com/package/js-beautify 
        },
        outputFile: "test/index.html"
    });

    Custom sorting

    You can change the order of appearance with the sortBy option. Any key from the Yaml data can be used, like title or section. If you want to keep the order as written in your CSS files, use fileOrder.

    // ... 
    sg.render({
        sortBy: ['section', 'title'], // default 
        // ... 
    });

    Hide items

    If you set visible: false in your YAML, it won't show up in your styleguide. This is mostly useful when working with includes.

    /***
      title: My title
      section: My Section
      visible: false
      example:
        <div class="invisible">I won't show up inside your styleguide</div>
    ***/

    Micro template

    When using includes you can use template strings inside your example. Use {attribute}="attribute data" inside your include tag. Anything in the include template matching exactly {attribute} will be replaced by its value.

    /***
      title: Override classnames
      section: Whatever
      id: includeId
      visible: false
      example:
        <div class="{templateVars}">
          {templateVars}
        </a>
    ***/
     
    /***
      title: Override classnames
      section: Whatever
      example:
        <include id="includeId" {templateVars}="template-data" />
    ***/

    will render

      <div class="template-data">
        template-data
      </a>

    Grunt task

    See grunt-styleguidejs for using styleguide.js inside your gruntfile.

    Gulp task

    See gulp-styleguidejs for using styleguide.js as a gulp plugin.

    Keywords

    none

    install

    npm i styleguidejs

    Downloadslast 7 days

    89

    version

    0.1.10

    license

    MIT

    last publish

    collaborators

    • avatar
    • avatar