metalsmith-kss

metalsmith-kss

A Metalsmith plugin to create KSS documentation.

Status

Installation

$ npm install metalsmith-kss

CLI Usage

Install via npm and then add the metalsmith-kss key to your metalsmith.json plugins, like so:

{
  "plugins": {
    "metalsmith-kss": {
      "...": "..."
    }
  }
}

Javascript Usage

Pass options to the kss plugin and pass it to Metalsmith with the use method:

var kss = require('metalsmith-kss');

metalsmith.use(kss({
  source: 'css/',              // Required: Where to look for KSS-documented CSS files
  target: 'styleguide/',       // Required: Where to store the output files.
  sectionQuery: '2.x.x',       // Optional: Query to pass to the KSS section() method. Default: none
  maxDepth: 1,                 // Optional: Section level at which to start adding content to the parent. Default: none
  template: 'custom-kss.html', // Optional: Path to custom (Handlebars) template. Default: './templates/kss.hbs'
  pageTemplate: 'page.html',   // Optional: Path to custom (Handlebars) page template. Default: none
  flatten: false,              // Optional: Whether to flatten the KSS section hierarchy. Default: false
  fixtures: { foo: '<input>' } // Optional: Provide an object with external fixtures. Default: {}
  options: {                   // Optional: Options to pass to the KSS traverse() method. Default: {}
    mask : '*.less|*.css',
    markdown  : true,
    multiline: false,
    typos: false
  }
}));

External fixtures

KSS lacks the ability to include external fixtures in the markup section. Here is how to work around this: Say, you have an external HTML fixture in your site that you like to appear in the markup section of your KSS styleguide so you don't have to do updates twice.

• In your KSS, put the following in the according markup section:

// Styleguide x
//
// ...
//
// Markup: {{> path/to/external_fixture}}

• In your metalsmith build file, add an object of all fixture files that you need to be available to KSS:

metalsmith(__dirname)
    .clean(true)
    .metadata(meta)
    .use(kss({ source: 'less/', target: 'styleguide/', pageTemplate: 'page.html', fixtures: { 'path/to/external_fixture': '<input name="foo">' } }))

TODOs

• Allow other template engines

License

MIT