Generate usage guides for css
A tool for generating usage and styles guides for html components using css block comments.
By adding a Topdoc block to your css you can describe an html/css component and that information can be used to generate a styleguide.
Here's an example component:
/* topdocname: Selectdescription: a dropdown selectmarkup: |<select name="select"><option value="value1">Value 1</option><option value="value2" selected>Value 2</option><option value="value3">Value 3</option></select>tags:- desktop- mobile- select*/
Topdoc was originally created for Topcoat and the one feature missing from other generators was support for any and all custom properties. Topdoc is extremely tolerant of custom properties, it just passes them to the template which defines what to do with it.
The only required properties are
markup, other than that, use whatever you need.
Install with npm. It's meant to be command line tool, so you probably want to install it globally (with
npm install -g topdoc
You can also use it as a npm script without install it globally. Super helpful for automating your styleguide building:
npm install --save-dev topdoc
package.json file use a script to call the topdoc cli too:
With it setup you can then run it from the command line using:
npm run docs
Topdoc uses PostCSS to divide asunder your css document and find all the relevant component information.
Below is an example of a Topdoc comment.
/* topdocname: Buttondescription: A simple buttonmodifiers::active: Active state.is-active: Simulates an active state on mobile devices:disabled: Disabled state.is-disabled: Simulates a disabled state on mobile devicesmarkup: |<a class="topcoat-button">Button</a><a class="topcoat-button is-active">Button</a><a class="topcoat-button is-disabled">Button</a>example:tags:- desktop- light- mobile- button- quietblarg: very true*/
Topdoc comments are identified by the
topdoc keyword on the first comment line.
The rest of the data uses a YAML friendly syntax.
The fields can be in any order, but this is a good example for consistency sake.
The following are recommend and/or required fields:
name(required): The full name of the component. Feel free to use spaces, punctuation, etc (name: Sir Button III, esq.)
description: Something more descriptive then the title alone.
modifiers: These can be pseudo classes, or addition rules applied to the component. This must be a YAML mapping (
*modifier*:*description*) which becomes a js hash
markup(required): This is the magic; it's the html that will be used to display the component in the docs. As most markup fields are long, make sure to use the
|for multiline values.
/* topdocname: Buttonmarkup: |<a class="topcoat-button">Button</a><a class="topcoat-button is-active">Button</a><a class="topcoat-button is-disabled">Button</a>*/
tags: Just some obligatory metadata.
blarg: Since Topdoc uses a flexible YAML syntax, feel free to add any additional custom data you might need for your template.
Topdoc assumes everything between two Topdoc comments, and everything after the last Topdoc comment, is a component. Put anything that isn't a component (general styles) above the first Topdoc comment.
However, the idea of css components is pretty loose because it is rare to have all the required styles for a component in one place.
Originally Topdoc was designed to split up the css into components to then use that css in the styleguild to show as a snippet, but honestly that snippet wasn't enough to make the component by itself so it really is only interesting as reference.
The output of the help command.
$ topdoc --helpUsage: topdoc topdoc [<css-file> | <directory> [default: src]] [options]Generate usage guides
Specify a source directory with
--source. Defaults to
topdoc -s release/css/
Specify a destination with
--destination. Defaults to
topdoc -d topdocs/
Specify a template with
--template. A default template is included in Topdoc if one is not provided.
The template can be a single jade file:
topdoc -t template/template.jade
or a directory (it will duplicate the whole template directory and look for index.jade in the template folder provided):
topdoc -t /template
This includes npm installed templates
topdoc -t node_modules/topdoc-theme
The project title will be passed through to the jade template file.
topdoc -p Awesome
In the jade file it is
All the options can be configured in the package.json file. This is super helpful if you are always using the same configuration. It will look in the package.json file if it exists, but can be overridden by the command line options.
Also, additional data can be passed through to the jade template. Below is an example:
In the jade template the data is accessible using
CSS for clean and fast web apps
The jade template has data passed through by default:
document object contains relevant information about just the current document being generated below is an example:
nav object contains names and urls to all the generated html files. In the jade template this can utilized to create a navigation to the other pages.
nav.site: ul- each item in nav- if(item.url == document.url)li.selected: a(href=item.url)=item.text- elseli: a(href=item.url)=item.text
project object contains relevant project information. Currently it only contains the
title property. (passed through the command line
-p option, or through the package.json information).
As mentioned above, additional data can be passed through to the template in the package.json file. This is accessible in the template as the
templateData object. See the example above.