0.3.2 • Published 9 years ago
metalsmith-kss v0.3.2
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