Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 136 lines (91 sloc) 6.557 kb
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
1 [![Build Status](https://secure.travis-ci.org/kss-node/kss-node.png?branch=master)](http://travis-ci.org/kss-node/kss-node)
bdc3346 @hughsk Update README.md
hughsk authored
2
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
3 # kss-node
4
7a2a95a @JohnAlbin Update README.
JohnAlbin authored
5 This is a Node.js implementation of [Knyle Style Sheets](https://github.com/kneath/kss) (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".
6
7 1. Write human-readable documentation using "KSS syntax" comments.
8 2. Have `kss-node` auto-generate a style guide from your stylesheets.
9
10 Here's an example KSS comment:
11 ```scss
12 // Button
13 //
14 // Your standard button suitable for clicking.
15 //
16 // :hover - Highlights when hovering.
17 // .shiny - Do not press this big, shiny, red button.
18 //
19 // Style guide: components.button
20 .button {
21 ...
22 }
23 .button.shiny {
24 ...
25 }
26 ```
27
28 The methodology and ideas behind Knyle Style Sheets are contained in [the specification](https://github.com/kss-node/kss/blob/spec/SPEC.md).
bdc3346 @hughsk Update README.md
hughsk authored
29
85e34d9 @JohnAlbin Update GitHub project URLs, e.g. from hughsk to kss-node.
JohnAlbin authored
30 There's an example project in the [demo directory](https://github.com/kss-node/kss-node/tree/master/demo) of this repo.
bdc3346 @hughsk Update README.md
hughsk authored
31
32 ## Installation
33
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
34 Just one line: `npm install kss`. Or, if you have a package.json for your project, with: `npm install kss --save-dev`.
35
36 After that, the command line tool can be found at `./node_modules/.bin/kss-node`.
37
38 If you know what you are doing, you can install it globally with: `npm install -g kss`
bdc3346 @hughsk Update README.md
hughsk authored
39
40 ## Using the CLI
41
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
42 To get you up and running quickly, a style guide generator is included that can be used from the command line. It parses stylesheets and spits out a set of static HTML files.
bdc3346 @hughsk Update README.md
hughsk authored
43
44 ```
8be7db8 @JohnAlbin Reorganize CLI options.
JohnAlbin authored
45 Usage: kss-node <source> [destination] [options]
d6b7a2d @JohnAlbin Update README for 1.0.0. Fixes #95
JohnAlbin authored
46
bdc3346 @hughsk Update README.md
hughsk authored
47 Options:
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
48 --init, -i Create a new style guide template to customize
3211171 @JohnAlbin Update CLI help text in README.
JohnAlbin authored
49 [default: "styleguide-template"]
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
50 --template, -t Use a custom template to build your style guide
3211171 @JohnAlbin Update CLI help text in README.
JohnAlbin authored
51 [default: "lib/template"]
8be7db8 @JohnAlbin Reorganize CLI options.
JohnAlbin authored
52 --helpers Specify the location of custom handlebars helpers; see
53 http://bit.ly/kss-helpers [default: "lib/template/helpers"]
54 --mask, -m Use a mask for detecting files containing KSS comments
55 [default: "*.css|*.less|*.sass|*.scss|*.styl|*.stylus"]
78fbc99 @JohnAlbin Custom fields for sections. Fixes #131
JohnAlbin authored
56 --custom Process a custom property name when parsing KSS comments
8be7db8 @JohnAlbin Reorganize CLI options.
JohnAlbin authored
57
bef4da5 @JohnAlbin Add --css and --js options to include URLs of CSS/JS files. #152
JohnAlbin authored
58 --css Specify the URL of a CSS file to include in the style guide
59 --js Specify the URL of a JavaScript file to include in the style
60 guide
61
8be7db8 @JohnAlbin Reorganize CLI options.
JohnAlbin authored
62 --source Source directory to parse for KSS comments
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
63 --destination Destination directory of generated style guide
3211171 @JohnAlbin Update CLI help text in README.
JohnAlbin authored
64 [default: "styleguide"]
684d685 @JohnAlbin Update CLI help text.
JohnAlbin authored
65
8be7db8 @JohnAlbin Reorganize CLI options.
JohnAlbin authored
66 --config, -c Load the kss-node configuration from a json file
67
68 --version Show version number
69 --help, -h, -? Show help
bdc3346 @hughsk Update README.md
hughsk authored
70 ```
71
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
72 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.
73
74 The generated style guide will be put into the `styleguide` directory unless you specify the second argument or use a `--destination [directory]` flag.
75
e2b7fdf @JohnAlbin Update --xdemo option to properly include CSS with --css.
JohnAlbin authored
76 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 template with `--init`.
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
77
78 You can generate a copy of the demo style guide like so:
bdc3346 @hughsk Update README.md
hughsk authored
79
a1da504 @JohnAlbin Remove CLI example that suggests wrong usage.
JohnAlbin authored
80 $ kss-node --xdemo
bdc3346 @hughsk Update README.md
hughsk authored
81
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
82 It is recommended that you create your own template, i.e. skin, theme. Use the `kss-node --init` command to initialize a copy of the default template so you can edit it and use it when generating your style guide with the `--template` flag. Simply link the generated CSS (as well as JS, etc.) from inside the custom template's index.html.
d6b7a2d @JohnAlbin Update README for 1.0.0. Fixes #95
JohnAlbin authored
83
84 $ kss-node --init custom-template
852ffb9 @JohnAlbin Update cli options in README.
JohnAlbin authored
85 $ kss-node path/to/sass styleguide --template custom-template
d6b7a2d @JohnAlbin Update README for 1.0.0. Fixes #95
JohnAlbin authored
86
87 The default template should look something like this:
bdc3346 @hughsk Update README.md
hughsk authored
88
d6b7a2d @JohnAlbin Update README for 1.0.0. Fixes #95
JohnAlbin authored
89 ![CLI Template Preview](https://raw.github.com/kss-node/kss-node/master/demo/preview.png)
bdc3346 @hughsk Update README.md
hughsk authored
90
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
91 ## Differences from kneath/kss
92
93 Unlike the default Ruby implementation at kneath/kss, kss-node includes a few optional features to allow for completely automated style guide generation.
bdc3346 @hughsk Update README.md
hughsk authored
94
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
95 **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 generate 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.
96
97 **Homepage Text**. The overview text needed for the style guide homepage is generated from a Markdown file, which you should place in a `--source` directory, just name it `styleguide.md` and it will be included in the final style guide automatically.
98
99 Additional kss-node specifics are detailed in this version of the [KSS spec](https://github.com/kss-node/kss/blob/spec/SPEC.md).
100
101 Take a look at the [demo project](https://github.com/kss-node/kss-node/tree/master/demo) for some examples.
102
103 ## Using kss-node from Node.js
104
105 Check out the [Module API](https://github.com/kss-node/kss-node/wiki/Module-API) for a full explanation. Here's an example:
bdc3346 @hughsk Update README.md
hughsk authored
106
107 ``` javascript
108 var kss = require('kss'),
109 options = {
110 markdown: false
111 };
112
113 kss.traverse('public/stylesheets/', options, function(err, styleguide) {
114 if (err) throw err;
115
116 styleguide.section('2.1.1') // <KssSection>
117 styleguide.section('2.1.1').modifiers(0) // <KssModifier>
118 styleguide.section('2.1.1').modifiers(':hover').description() // 'Subtle hover highlight'
119 styleguide.section('2.1.1').modifiers(0).className() // 'pseudo-class-hover'
120 styleguide.section('2.x.x') // [<KssSection>, ...]
121 styleguide.section('2.1.1').modifiers() // [<KssModifier>, ...]
122 });
123 ```
124
125 ## Development
126
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
127 Forking, hacking, and tearing apart of this software is welcome! It still needs some cleaning up.
bdc3346 @hughsk Update README.md
hughsk authored
128
129 If you've got [mocha](https://github.com/visionmedia/mocha) installed, you can run the module's tests with `npm test` or `make test`.
130
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
131 To generate a new version of the demo style guide, use `make gh-pages`. 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.
bdc3346 @hughsk Update README.md
hughsk authored
132
133 ## Contributors
134
927dd31 @JohnAlbin Update README.md to show 2.x features. #156
JohnAlbin authored
135 Lots! And more are welcome. https://github.com/kss-node/kss-node/graphs/contributors
Something went wrong with that request. Please try again.