The Node.js port of KSS: A methodology for documenting CSS and building style guides
Note: This README is for the
master branch of this project. To see the README for the latest stable release see https://www.npmjs.com/package/kss.
This is a Node.js implementation of Knyle Style Sheets (KSS), "a documentation syntax for CSS" that's intended to have syntax readable by humans and machines. Hence, the kss-node software can be used to create a "living style guide".
kss-nodeautomatically build a style guide from your stylesheets.
Here's an example KSS comment:
// Button//// Your standard button suitable for clicking.//// :hover - Highlights when hovering.// .shiny - Do not press this big, shiny, red button.//// Markup: button.html//// Style guide: components.button.button.button.shiny
The methodology and ideas behind Knyle Style Sheets are contained in the specification.
There's an example project in the demo directory of this repo.
kss-node is installed just like any other Node.js software. Read the kss-node Quick Start Guide to learn more. It also includes an npm Quick Start Guide, if you don't know much about Node.js's npm command.
To get you up and running quickly, a style guide builder is included that can be used from the command line. It parses stylesheets and spits out a set of static HTML files.
Since each builder has its own set of options, you can see the help for those options by using
--help. For example, running
kss-node --help --builder builder/twig will show these additional options:
Style guide:--extend Location of modules to extend Twig.js; see--extend-drupal8 Extend Twig.js using kss's Drupal 8 extensions--namespace Adds a Twig namespace, given the formatted string:"namespace:path"
In order to parse your stylesheets containing KSS docs, you need to either specify a single directory as the first argument or you can specify one or more source directories with one or more
--source [directory] flags.
The style guide will be built in the
styleguide directory unless you specify the second argument or use a
--destination [directory] flag.
Even though kss-node parses your CSS source, your CSS won't be included in the style guide unless you use the
--css option or create a custom builder with
You can build a copy of the demo style guide like so:
$ kss-node --demo
If you want to change the HTML of the style guide being built, you can create your own builder, i.e. skin, theme. Use the
kss-node --clone command to initialize a copy of the default builder so you can edit it and use it when building your style guide with the
$ kss-node --clone custom-builder $ kss-node path/to/sass styleguide --builder custom-builder
The default builder should look something like this:
Unlike the default Ruby implementation at kneath/kss, kss-node includes a few optional features to allow for completely automated style guide building.
Language Agnostic. kss-node does not care what language your application is written in (Ruby, Node.js, PHP, whatever). It just scans your CSS source files looking for KSS docs so that it can build a living style guide. And since it only looks for properly formatted KSS comments, it also doesn't need to know what kind of CSS preprocessor you use either.
Homepage Text. The overview text needed for the style guide homepage is built from a Markdown file, which you should place in a
--source directory, just name it
homepage.md and it will be included in the final style guide automatically.
Additional kss-node specifics are detailed in this version of the KSS spec.
Take a look at the demo project for some examples.
var kss = require'kss'options =markdown: false;ksstraverse'public/stylesheets/' optionsif error throw error;styleGuidesections'2.1.1' // <KssSection>styleGuidesections'2.1.1'modifiers0 // <KssModifier>styleGuidesections'2.1.1'modifiers':hover'description // 'Subtle hover highlight'styleGuidesections'2.1.1'modifiers0className // 'pseudo-class-hover'styleGuidesections'2.x.x' // [<KssSection>, ...]styleGuidesections'2.1.1'modifiers // [<KssModifier>, ...];
Forking, hacking, and tearing apart of this software is welcome! It still needs some cleaning up.
After you've cloned this repository, run
npm install and then you'll be able to run the module's mocha and eslint tests with
To build a new version of the demo style guide, use
make docs. After committing your changes to master you can use the
gh-pages.sh script to move this over to the
gh-pages branch real quick.
Lots! And more are welcome. https://github.com/kss-node/kss-node/graphs/contributors