LivingCSS

Parse comments in your CSS to generate a living style guide using Markdown, Handlebars, Polymer, and Prism syntax highlighter.

Installation

$ npm install --save livingcss

Demos

See the github page for an example of the default output of LivingCSS.

See FamilySearch.org Style Guide for an example of using LivingCSS with custom tags and a custom Handlebars template. This gist shows the gulpfile and Handlebars template used by the FamilySearch Style Guide.

Gulp

Use gulp-livingcss

var gulp = require('gulp');
var livingcss = require('gulp-livingcss');

gulp.task('default', function () {
  gulp.src('src/styles.css')
    .pipe(livingcss())
    .pipe(gulp.dest('dist'))
});

Usage

var livingcss = require('livingcss');

// livingcss(source, dest, options)
livingcss('input.css', 'styleguide', options);

• source - A file path, glob, or mixed array of both, matching files to be parsed to generate the style guide. Any file type can be used so long as it allows /** */ type comments.
• dest - Directory to output the style guide HTML. Defaults to the current directory.
• options - optional list of options.

How it works

LivingCSS parses JSDoc-like comments for documentation in order to create a living style guide. A documentation comment follows the following format.

/**
 * A short description or lengthy explanation about the style. Will be parsed
 * using `markdown`.
 *
 * Descriptions can be multiple lines and end at the first encountered tag.
 * Tags can be in any order and can be multiple lines long as well.
 *
 * @section Section Name
 * @example
 * <div class="my-awesome-class">Example</div>
 */

What makes LivingCSS different than other tag-like comment parsers is that it does not try to impose a strict tag rule set. Instead, it defines a few basic tags for you to use, but any tag will be parsed so long as it follows the @tag {type} name - description format (where type, name, and description are all optional).

It also generates a JSON object of the parsed comments that can be used to generate style guides using other templating languages.

Defined tags

• @tag {type} name - description - Any tag that follows this format will be parsed. The type, name, and description are all optional. If only the tag is defined, the description will be set to true. Multiple tags with the same name will be added as an array in the context object.

  • If the type is {markdown}, the description will be parsed as markdown.

    /**
     * @tag {markdown} *Will* be parsed as `markdown`.
     */
    

    /**
     * Example of multiple tags with the same name. Will result in:
     *   
     *     { 
     *       color: [
     *         {name: 'Red', description: '#f00'}, 
     *         {name: 'Green', description: '#0f0'},
     *         {name: 'Blue', description: '#00f'}
     *       ]
     *     }
     *
     * @color Red - #f00
     * @color Green - #0f0
     * @color Blue - #00f
     */
    

• @section - Add a new section to the style guide. The @section tag can define the name of the section or the first line of the comment description will be used as the section name.

  /**
   * My Section
   *
   * A description of the section and how to use it.
   *
   * @section
   */
  
  /**
   * A description of the section and how to use it.
   *
   * @section My Section
   */
  

• @sectionof - Add a section as a child of another section. There is no limit to the number of nested sections. If the section you are referencing is a child of another section, then the value of @sectionof must use all parent section names delimited by a period.

  /**
   * A description of the parent section.
   *
   * @section Parent Section
   */
  
  /**
   * A description of the child section.
   *
   * @section Child Section
   * @sectionof Parent Section
   */
  
  /**
   * A child of Child Section
   *
   * @section Grandchild Section
   * @sectionof Parent Section.Child Section
   */
  
  /**
   * A child of Grandchild Section
   *
   * @section Great-grandchild Section
   * @sectionof Parent Section.Child Section.Grandchild Section
   */
  

• @page - Add a section to a page. Each unique page will output its own HTML file. Child sections will inherit the page of the parent. Defaults to index.

  /**
   * Section belonging to a page.
   *
   * @section Section Name
   * @page Page Name
   */
  

• @example - Provide an example that will be displayed in the style guide. Can provide a type to change the language for code highlighting, and you can also provide a file path to be used as the example. See Prisms supported languages for valid types.

  /**
   * A simple example.
   *
   * @section Example
   * @example
   * <div>foo</div>
   */
  
  /**
   * An example with a language type.
   *
   * @section Example
   * @example {javascript}
   * console.log('foo');
   */
  
  /**
   * An example from a file
   *
   * @section Example
   * @example
   * relative/path/to/file.html
   */
  

  NOTE: By default, the style guide only loads Prism markup (HTML) syntax highlighting. If you need another syntax language (use files for v1.6.0), you'll have to add it to the context.scripts array.

• @code - Same as @example, but can be used to override the code output to be different than the example output. Useful if you need to provide extra context for the example that does not need to be shown in the code. If you need to use the @ symbol at the start of a newline (such as with @extend or @include in CSS preprocessors), use the HTML entity encoding @, otherwise the parser will try to parse it as a tag.

  /**
   * Different example output than code output
   *
   * @section Code Example
   * @example
   * <div class="container">
   *   <div class="my-awesome-class">Example</div>
   * </div>
   *
   * @code
   * <div class="my-awesome-class">Example</div>
   */
   
  /**
   * Using the @ symbol in code
   *
   * @section Code With At Symbol
   * @code
   * .example {
   *   &#64;extend %placeholder-selector;
   * }
   */
  

• @hideCode - Hide the code output of the example.

  /**
   * You can only see the example, the code is hidden.
   *
   * @section hideCode Example
   * @example
   * <div class="container">
   *   <div class="my-awesome-class">Example</div>
   * </div>
   * @hideCode
   */
  

• @doc - A file that defines the section name, description, example, or code. Useful if your section description needs to output HTML. The first heading of the file will be used as the section description if one is not defined.

  /**
   * @doc externalDoc.md
   * @section
   */
  

  
  [//]: # "externalDoc.md"
  # Section Title
  
  This markdown file can define the `@section` name using a heading and the section description. Anything that is not an `@example` or `@code` code block will be added to the description of the section.
  
  ```
  This code block will be part of the description.
  ```
  
  ```html
  @example
  <p>This code block will be treated as the <code>@example</code> tag</p>
  ```
  
      @code
      <p>This code block will be treated as the <code>@code</code> tag.</p>
      <p>You can use either the triple ticks or 4 spaces when defining the <code>@example</code> or <code>@code</code> blocks.</p>
  

  NOTE: Because @doc can provide a section name, the @section tag must come after the @doc tag, otherwise you will get an Unnamed Section error.

Options

• loadcss - If the style guide should load the css files that were used to generate it. The style guide will not move the styles to the output directory but will merely link to the styles in their current directory (so relative paths from the styles still work). Defaults to true.
• minify - If the generated HTML should be minified. Defaults to false.
• preprocess - Function that will be called for every page right before Handlebars is called with the context object. The function will be passed the context object, the template, and the Handlebars object as parameters. Return false if you don't want the style guide to be generated using Handlebars, or return a Promise if you need to make asynchronous calls (reject the Promise to not use Handlebars). Use this function to modify the context object, add additional styles to the examples, or register Handlebars partials, helpers, or decorators.
• sortOrder - List of pages and their sections in the order they should be sorted. Any page or section not listed will be added to the end in the order encountered. Can be an array of page names to just sort pages, an array of objects with page names as keys and an array of section names as values to sort both pages and sections, or a mix of both. Names are case insensitive.
• tags - Object of c