README.md

CSS Documentation support for SourceJS

Appends rendered DSS documentation into SourceJS Spec pages. Watch rendered example Spec and it's source code.

SourceJS plugin (for 0.5.0+ version).

Install

To install middleware, run npm command in sourcejs/user folder:

npm install sourcejs-contrib-dss --save

After restarting your app, middleware will be loaded automatically. To disable it, remove npm module and restart the app.

Usage

DSS works as SourceJS middleware, when Spec (documentation page) is requested, plugin is searching CSS files in Spec folder by defined mask.

All found CSS (or LESS/SASS/SCSS/Stylus) will be processed through DSS in runtime, during request.

Here's an example of Spec folder structure

specs/button
    button.css
    readme.md
    info.json

button.css contents:

/**
  * @name Default
  *
  * @state .button-pro_big - Bigger version
  *
  * @markup
  *   <button class="button-pro">Click me</button>
  */

.button-pro {}
.button-pro.button-pro_big {}

/**
  * @name Disabled
  *
  * @state .button-pro_big - Bigger disabled version
  *
  * @markup
  *   <button class="button-pro button-pro_disabled">Click me</button>
  */

.button-pro.button-pro_disabled {}

Spec rendered result (http://127.0.0.1:8080/specs/button):

readme.md contents will be rendered at the top of Spec file. Other file types as index.src or index.jade (with Jade plugin) could also be used.

Note that Spec file and info.json should be present in folder for page to load.

Options

You can configure plugin options from user/options.js:

{
    core: {},
    assets: {},
    plugins: {
        dss: {
           targetCssMask: '**/*.{css,less,stylus,sass,scss}',
           visibleCode: true,
           templates: {
               sections: path.join(__dirname, '../views/sections.ejs')
           }
        }
    }
}

targetCssMask

Type: String Default value: **/*.{css,less,stylus,sass,scss}

Glob mask for searching CSS files for DSS parsing, starting from requested Spec path (https://github.com/isaacs/node-glob).

visibleCode

Type: Boolean Default: true

Set source_visible to every src-html code containers to show code preview by default. Set to false if you prefer hiding code blocks by default (toggled from menu Show source code).

templates

Type: Object

templates.item

Type: String Default: path.join(__dirname, '../views/sections.ejs')

Set path to EJS template for rendering DSS JSON result. Currently this plugin uses only one template for sections.

Upcoming features

• DSS parser caching
• Pre-build cache (during app start)
• DSS improvements

Other SourceJS middlewares

• https://github.com/sourcejs/sourcejs-jade
• https://github.com/sourcejs/sourcejs-smiles