15 | //
16 | // :hover - Subtle hover highlight.
17 | // .stars-given - A highlight indicating you've already given a star.
18 | // .stars-given:hover - Subtle hover highlight on top of stars-given styling.
19 | // .disabled - Dims the button to indicate it cannot be used.
20 | //
21 | // Style guide 2.1.3.
22 | a.button.star{
23 | background:#ddd;
24 |
25 | &.star-given{
26 | }
27 | &.disabled{
28 | }
29 | }
30 |
31 | // A button suitable for giving stars to someone.
32 | //
33 | // :hover - Subtle hover highlight.
34 | // .stars-given - A highlight indicating you've already given a star.
35 | // .stars-given:hover - Subtle hover highlight on top of stars-given styling.
36 | // .disabled - Dims the button to indicate it cannot be used.
37 | //
38 | // Style guide 2.1.4.
39 | a.button.star{
40 | background:#ddd;
41 |
42 | &.star-given{
43 | }
44 | &.disabled{
45 | }
46 | }
47 |
48 | // Section 3
49 | //
50 | // Section 3 has been successfully loaded.
51 | //
52 | // Style guide 3
53 |
54 | // Forms
55 | //
56 | // Markup: forms.twig
57 | //
58 | // Style guide 3.1
59 |
60 | // Single-Line Text Boxes
61 | //
62 | // Markup:
63 | //
64 | // Nested Twig template part 1:
65 | //
66 | // Style guide 3.1.1
67 |
68 | // Submit button
69 | //
70 | // Markup: button.twig
71 | //
72 | // Style guide 3.1.2
73 |
74 | // Custom properties
75 | //
76 | // Custom: This is the first custom property.
77 | //
78 | // Custom2: This is the second custom property.
79 | //
80 | // Style guide 4.1
81 |
--------------------------------------------------------------------------------
/test/helper.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | // Globals for all test_*.js files. Add these to .eslintrc too.
4 | global.chai = require('chai');
5 | global.kss = require('kss');
6 | global.path = require('path');
7 | global.Promise = require('bluebird');
8 | global.expect = chai.expect;
9 | global.fs = Promise.promisifyAll(require('fs-extra'));
10 |
11 |
12 | // Create a helper utility object.
13 | global.helperUtils = {
14 | // Returns the full path to the test fixtures in test/fixtures or sub-directory.
15 | fixtures: function() {
16 | // Add the fixtures path to the start our list of paths.
17 | let args = Array.prototype.slice.call(arguments);
18 | args.unshift('fixtures');
19 | args.unshift(__dirname);
20 | return path.join.apply(this, args);
21 | },
22 |
23 | // Simplifies usage of kss.traverse() in various tests.
24 | traverseFixtures: function(options) {
25 | return kss.traverse(this.fixtures(), options).then(styleGuide => {
26 | expect(styleGuide.sections()).to.be.ok;
27 | return styleGuide;
28 | }, error => {
29 | expect(error).to.not.exist;
30 | });
31 | }
32 | };
33 |
34 | // This before() is run before any tests in the test_*.js files.
35 | before(function() {
36 | // Add custom assertions.
37 | chai.use(function(chai) {
38 | let Assertion = chai.Assertion;
39 |
40 | // .containFixture(string) asserts that a given file should be in an array.
41 | Assertion.addMethod('containFixture', function(file) {
42 | file = path.resolve(helperUtils.fixtures(), file);
43 | this.assert(
44 | this._obj.meta.files.indexOf(file) >= 0,
45 | 'to contain the file named #{exp}, but contained #{act}',
46 | 'to not contain the file named #{exp} in #{act}',
47 | file,
48 | this._obj.meta.files
49 | );
50 | });
51 | });
52 | });
53 |
54 | // We want to clean-up the test/output directory unless we are testing a single
55 | // it.only() test.
56 | let cleanup = false;
57 |
58 | // This test is skipped if another test is set to .only().
59 | describe('Ensure test suite cleans up after itself', function() {
60 | it('should remove test/output directory', function() {
61 | cleanup = true;
62 | });
63 | });
64 |
65 | after(function() {
66 | if (cleanup) {
67 | return fs.removeAsync(path.resolve(__dirname, 'output'));
68 | }
69 | });
70 |
--------------------------------------------------------------------------------
/.eslintrc:
--------------------------------------------------------------------------------
1 | {
2 | // http://eslint.org/docs/user-guide/configuring.html
3 | "root": true,
4 | "extends": "eslint:recommended",
5 | "env": {
6 | "node": true,
7 | "es6": true
8 | },
9 | "parserOptions": {
10 | "ecmaVersion": 6
11 | },
12 | "rules": {
13 | // Errors.
14 | "array-bracket-spacing": [2, "never"],
15 | "block-scoped-var": 2,
16 | "brace-style": [2, "1tbs", {"allowSingleLine": true}],
17 | "camelcase": 2,
18 | "comma-dangle": [2, "never"],
19 | "comma-spacing": 2,
20 | "comma-style": [2, "last"],
21 | "computed-property-spacing": [2, "never"],
22 | "consistent-this": [2, "self"],
23 | "curly": [2, "all"],
24 | "eol-last": 2,
25 | "eqeqeq": [2, "smart"],
26 | "guard-for-in": 2,
27 | "indent": [2, 2, {"SwitchCase": 1}],
28 | "key-spacing": [2, {"beforeColon": false, "afterColon": true}],
29 | "keyword-spacing": 2,
30 | "linebreak-style": [2, "unix"],
31 | "max-nested-callbacks": [2, 3],
32 | "new-parens": 2,
33 | "no-array-constructor": 2,
34 | "no-caller": 2,
35 | "no-catch-shadow": 2,
36 | "no-eval": 2,
37 | "no-extend-native": 2,
38 | "no-extra-bind": 2,
39 | "no-implied-eval": 2,
40 | "no-iterator": 2,
41 | "no-label-var": 2,
42 | "no-labels": [2, {"allowLoop": true, "allowSwitch": true}],
43 | "no-lone-blocks": 2,
44 | "no-loop-func": 2,
45 | "no-mixed-requires": [2, false],
46 | "no-multi-spaces": 2,
47 | "no-multi-str": 2,
48 | "no-native-reassign": 2,
49 | "no-nested-ternary": 2,
50 | "no-new-func": 2,
51 | "no-new-object": 2,
52 | "no-new-wrappers": 2,
53 | "no-octal-escape": 2,
54 | "no-process-exit": 2,
55 | "no-proto": 2,
56 | "no-return-assign": 2,
57 | "no-script-url": 2,
58 | "no-sequences": 2,
59 | "no-shadow-restricted-names": 2,
60 | "no-spaced-func": 2,
61 | "no-throw-literal": 2,
62 | "no-trailing-spaces": 2,
63 | "no-undef-init": 2,
64 | "no-undefined": 2,
65 | "no-unused-expressions": 2,
66 | "no-unused-vars": 2,
67 | "no-with": 2,
68 | "object-curly-spacing": [2, "never"],
69 | "quote-props": [2, "consistent-as-needed"],
70 | "quotes": [2, "single", "avoid-escape"],
71 | "semi": [2, "always"],
72 | "semi-spacing": [2, {"before": false, "after": true}],
73 | "space-before-function-paren": [2, "never"],
74 | "space-in-parens": [2, "never"],
75 | "space-infix-ops": 2,
76 | "space-unary-ops": [2, { "words": true, "nonwords": false }],
77 | "spaced-comment": [2, "always"],
78 | "strict": [2, "global"],
79 | "valid-jsdoc": [2, {
80 | "prefer": {
81 | "return": "returns"
82 | },
83 | "requireReturn": false
84 | }],
85 | "wrap-iife": 2,
86 | "yoda": [2, "never"],
87 | // Disabled.
88 | "no-console": 0
89 | }
90 | }
91 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | [](http://travis-ci.org/kss-node/kss-node/builds) [](https://coveralls.io/github/kss-node/kss-node?branch=master) [](https://david-dm.org/kss-node/kss-node)
2 |
3 | **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](https://www.npmjs.com/package/kss).
4 |
5 | # kss-node
6 |
7 | 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".
8 |
9 | 1. Write human-readable documentation using "KSS syntax" comments.
10 | 2. Have the `kss` tool automatically build a style guide from your stylesheets.
11 |
12 | Here's an example KSS comment:
13 | ```scss
14 | // Button
15 | //
16 | // Your standard button suitable for clicking.
17 | //
18 | // :hover - Highlights when hovering.
19 | // .shiny - Do not press this big, shiny, red button.
20 | //
21 | // Markup: button.html
22 | //
23 | // Style guide: components.button
24 | .button {
25 | ...
26 | }
27 | .button.shiny {
28 | ...
29 | }
30 | ```
31 |
32 | The methodology and ideas behind Knyle Style Sheets are contained in [the specification](https://github.com/kss-node/kss/blob/spec/SPEC.md).
33 |
34 | There's an example project in the [demo directory](https://github.com/kss-node/kss-node/tree/master/demo) of this repo.
35 |
36 | ## Installation
37 |
38 | kss-node is installed just like any other Node.js software. Read the [kss-node Quick Start Guide](https://github.com/kss-node/kss-node/wiki/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.
39 |
40 | ## Using the command line tool
41 |
42 | 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.
43 |
44 | ```
45 | Usage: kss [options]
46 |
47 | File locations:
48 | --source Source directory to recursively parse for KSS comments,
49 | homepage, and markup
50 | --destination Destination directory of style guide [default: "styleguide"]
51 | --mask, -m Use a mask for detecting files containing KSS comments
52 | [default: "*.css|*.less|*.sass|*.scss|*.styl|*.stylus"]
53 | --config, -c Load the kss options from a json file
54 |
55 | Builder:
56 | --clone Clone a style guide builder to customize
57 | --builder, -b Use the specified builder when building your style guide
58 | [default: "builder/handlebars"]
59 |
60 | Style guide:
61 | --css URL of a CSS file to include in the style guide
62 | --js URL of a JavaScript file to include in the style guide
63 | --custom Process a custom property name when parsing KSS comments
64 | --extend Location of modules to extend the templating system; see
65 | http://bit.ly/kss-wiki
66 | --homepage File name of the homepage's Markdown file
67 | [default: "homepage.md"]
68 | --markup Render "markup" templates to HTML with the placeholder text
69 | [default: false]
70 | --placeholder Placeholder text to use for modifier classes
71 | [default: "[modifier class]"]
72 | --nav-depth Limit the navigation to the depth specified [default: 3]
73 | --title Title of the style guide [default: "KSS Style Guide"]
74 |
75 | Options:
76 | --verbose Display verbose details while building
77 | --demo Builds a KSS demo.
78 | --help, -h, -? Show help
79 | --version Show version number
80 | ```
81 |
82 | Since each builder has its own set of options, you can see the help for those options by using `--builder` with `--help`. For example, running `kss --help --builder builder/twig` will show these additional options:
83 |
84 | ```
85 | Style guide:
86 | --extend-drupal8 Extend Twig.js using kss's Drupal 8 extensions
87 | --namespace Adds a Twig namespace, given the formatted string:
88 | "namespace:path"
89 | ```
90 |
91 | 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.
92 |
93 | The style guide will be built in the `styleguide` directory unless you specify the second argument or use a `--destination [directory]` flag.
94 |
95 | Even though kss 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 `--clone`.
96 |
97 | You can build a copy of the demo style guide like so:
98 |
99 | $ kss --demo
100 |
101 | 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 --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 `--builder` flag.
102 |
103 | $ kss --clone custom-builder
104 | $ kss path/to/sass styleguide --builder custom-builder
105 |
106 | The default builder should look something like this:
107 |
108 | 
109 |
110 | ## Differences from kneath/kss
111 |
112 | Unlike the default Ruby implementation at kneath/kss, kss-node includes a few optional features to allow for completely automated style guide building.
113 |
114 | **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.
115 |
116 | **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.
117 |
118 | Additional kss-node specifics are detailed in this version of the [KSS spec](https://github.com/kss-node/kss/blob/spec/SPEC.md).
119 |
120 | Take a look at the [demo project](https://github.com/kss-node/kss-node/tree/master/demo) for some examples.
121 |
122 | ## Using kss from Node.js
123 |
124 | Check out the [JavaScript API](http://kss-node.github.io/kss-node/section-javascript-api.html) for a full explanation. Here's an example:
125 |
126 | ``` javascript
127 | var kss = require('kss'),
128 | options = {
129 | markdown: false
130 | };
131 |
132 | kss.traverse('public/stylesheets/', options).then(function(styleGuide) {
133 | styleGuide.sections('2.1.1'); //
134 | styleGuide.sections('2.1.1').modifiers(0); //
135 | styleGuide.sections('2.1.1').modifiers(':hover').description(); // 'Subtle hover highlight'
136 | styleGuide.sections('2.1.1').modifiers(0).className(); // 'pseudo-class-hover'
137 | styleGuide.sections('2.x.x'); // [, ...]
138 | styleGuide.sections('2.1.1').modifiers(); // [, ...]
139 | });
140 | ```
141 |
142 | ## Development
143 |
144 | Forking, hacking, and tearing apart of this software is welcome! It still needs some cleaning up.
145 |
146 | 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 `npm test`.
147 |
148 | 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.
149 |
150 | ## Contributors
151 |
152 | Lots! And more are welcome. https://github.com/kss-node/kss-node/graphs/contributors
153 |
--------------------------------------------------------------------------------