Generate usage guides for css
A tool for generating usage guides for css.
Topdoc uses css-parse to divide asunder your css document and find all the relevant Topdoc comments.
Below is an example of a Topdoc comment, take a look, and then read the explanation under it.
/* 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 must start with
topdoc on the first comment line, it makes it quick and easy to identify from other comments.
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 psuedo 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.
tags: Just some obligitory 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.
Install with npm. It's meant to be command line tool, so you probably want to install it globally (with
npm install -g topdoc
The output of the help command.
-h, --help output usage information-s, --source <directory> The css source directory.-d, --destination <directory> The destination directory where the usage guides will be written.-t, --template <jade file/directory> The path to the jade template file. If it is a directory it will import all the sub files.-p. --project <title> The title for your project. Defaults to the directory name.-V, --version output the version number
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 thorugh 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.