node package manager

dss

DSS

DSS, Documented Style Sheets, is a comment styleguide and parser for CSS, LESS, STYLUS, SASS and SCSS code.

Generating Documentation

In most cases, you will want to include the DSS parser in a build step that will generate documentation files automatically. grunt-dss is the official DSS grunt task which does just that.

Parser Example

Example Comment Block

/**
  * @name Button
  * @description Your standard form button.
  * 
  * @state :hover - Highlights when hovering.
  * @state :disabled - Dims the button when disabled.
  * @state .primary - Indicates button is the primary action.
  * @state .smaller - A smaller button
  * 
  * @markup
  *   <button>This is a button</button>
  */ 

or

// 
// @name Button 
// @description Your standard form button. 
//  
// @state :hover - Highlights when hovering. 
// @state :disabled - Dims the button when disabled. 
// @state .primary - Indicates button is the primary action. 
// @state .smaller - A smaller button 
//  
// @markup 
//   <button>This is a button</button> 
//  

Example Parser Implementation

var lines = fs.readFileSync('styles.css'),
    options = {},
    callback = function(parsed){
      console.log(parsed);
    };
dss.parse(lines, options, callback);

Example Generated Object

{
  "name": "Button",
  "description": "Your standard form button.",
  "state": [
    { 
      "name": ":hover",
      "escaped": "pseudo-class-hover",
      "description": "Highlights when hovering."
    },
    {
      "name": ":disabled",
      "escaped": "pseudo-class-disabled",
      "description": "Dims the button when disabled."
    },
    {
      "name": ".primary",
      "escaped": "primary",
      "description": "Indicates button is the primary action."
    },
    {
      "name": ".smaller",
      "escaped": "smaller",
      "description": "A smaller button"
    }
  ],
  "markup": {
    "example": "<button>This is a button</button>",
    "escaped": "&lt;button&gt;This is a button&lt;/button&gt;"
  }
}

Modifying Parsers

DSS, by default, includes 4 parsers for the name, description, states and markup of a comment block. You can add to or override these default parsers using the following:

// Matches @link 
dss.parser('link', function(i, line, block){
 
  // Replace link with HTML wrapped version 
  var exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
  line.replace(exp, "<a href='$1'>$1</a>");
  return line;
   
});

DSS Sublime Text Plugin

You can now auto-complete DSS-style comment blocks using @sc8696's Auto-Comments Sublime Text Plugin

We ♥ your boss

Selectively mirror the npm registry inside your firewall. Filter packages based on security, licensing, code quality and more. Build awesome stuff faster. Try npm Enterprise for free…

how? learn more

Collaborators list

Stats

Try it out

Keywords

css, dss, styles, docs, documentation

Dependencies

None

Dependents (13)

postcss-dss, gulp-dss-extra, doki, gulp-dss, gulp-dss-annotation, grunt-css-docs, grunt-unicom-cssdoc, coatroom, sourcejs-contrib-dss, gulp-styleguide, grunt-dss, and more