Getting Started
Installation
Install with npm. It’s meant to be command line tool, so you probably want to install it globally (with -g).
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
In your package.json file use a script to call the topdoc cli too:
"scripts": {
"docs": "topdoc css/main.css"
}
With it setup you can then run it from the command line using:
npm run docs
Usage
Comment Format
Topdoc uses PostCSS to divide asunder your css document and find all the relevant component information.
Below is an example of a Topdoc comment.
/* topdoc
name: Button
description: A simple button
modifiers:
:active: Active state
.is-active: Simulates an active state on mobile devices
:disabled: Disabled state
.is-disabled: Simulates a disabled state on mobile devices
markup: |
<a class="topcoat-button">Button</a>
<a class="topcoat-button is-active">Button</a>
<a class="topcoat-button is-disabled">Button</a>
example: http://codepen.io/
tags:
- desktop
- light
- mobile
- button
- quiet
blarg: very true
*/
.topcoat-button,
.topcoat-button--quiet,
.topcoat-button--large,
.topcoat-button--large--quiet,
.topcoat-button--cta,
.topcoat-button--large--cta {
/* all your css junk here */
}
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 hashmarkup(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./* topdoc name: Button markup: | <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.
Components
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.
Help
The output of the help command.
$ topdoc --help
Usage: topdoc topdoc [<css-file> | <directory> [default: src]] [options]
Generate usage guides for css
Options:
-h, --help output usage information
-d, --destination <directory> [default: docs] directory where the usage guides will be written.
Like all the options, source can be definied in the config or package.json file.
-s, --stdout outputs the parsed topdoc information as json in the console.
-t, --template <directory> | <npm-package-name> [default: topdoc-default-template] path to template directory or package name.
Note: Template argument is resolved using the 'resolve' package.
-p, --project <title> [default: <cwd name>] title for your project.
-c, --clobber Deletes destination directory before running.
-i, --ignore-assets [<file> | <list of files>] A file or comma delimeted list of files in the asset directory that should be
ignored when copying them over.
-a, --asset-directory <path> Path to directory of assets to copy to destination. Defaults to template directory.
Set to false to not copy any assets.
-V, --version output the version number
Command Line
Source
Specify a source directory with -s or --source. Defaults to src/.
topdoc -s release/css/
Destination
Specify a destination with -d or --destination. Defaults to docs/.
topdoc -d topdocs/
Template
Specify a template with -t or --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
Project Title
The project title will be passed through to the jade template file.
topdoc -p Awesome
In the jade file it is project.title:
title=project.title
yeilds:
<title>Awesome</title>
package.json Configuration
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:
{
"name": "topcoat-test",
"version": "0.4.1",
"description": "CSS for clean and fast web apps",
"main": "Gruntfile.js",
"dependencies": {
"topdoc": "0.0.12"
},
"topdoc": {
"source": "release/css/",
"destination": "topdocs/",
"template": "node_modules/topdoc-theme",
"templateData": {
"title": "Topcoat",
"subtitle": "CSS for clean and fast web apps",
"download": {
"url": "#",
"label": "Download version 0.4"
},
"homeURL": "http://topcoat.io",
"siteNav": [
{
"url": "http://www.garthdb.com",
"text": "Usage Guidelines"
},
{
"url": "http://bench.topcoat.io/",
"text": "Benchmarks"
},
{
"url": "http://topcoat.io/blog",
"text": "Blog"
}
]
}
}
}
In the jade template the data is accessible using templateData:
p=templateData.subtitle
yeilds:
<p>CSS for clean and fast web apps</p>
Template
The jade template has data passed through by default:
Document Object
The document object contains relevant information about just the current document being generated below is an example:
{
"title": "Button",
"filename": "button.css",
"source": "test/cases/button.css",
"template": "lib/template.jade",
"url": "index.html",
"components": [
{
"name": "Button",
"slug": "button",
"details": ":active - Active state\n.is-active - Simulates an active state on mobile devices\n:disabled - Disabled state\n.is-disabled - Simulates a disabled state on mobile devices",
"markup": "<a class=\"topcoat-button\">Button</a>\n<a class=\"topcoat-button is-active\">Button</a>\n<a class=\"topcoat-button is-disabled\">Button</a>",
"css": ".topcoat-button,\n.topcoat-button--quiet,\n.topcoat-button--large,\n.topcoat-button--large--quiet,\n.topcoat-button--cta,\n.topcoat-button--large--cta {\n position: relative;\n display: inline-block;\n vertical-align: top;\n -webkit-box-sizing: border-box;\n -moz-box-sizing: border-box;\n box-sizing: border-box;\n -webkit-background-clip: padding;\n -moz-background-clip: padding;\n background-clip: padding-box;\n padding: 0;\n margin: 0;\n font: inherit;\n color: inherit;\n background: transparent;\n border: none;\n cursor: default;\n -webkit-user-select: none;\n -moz-user-select: none;\n -ms-user-select: none;\n user-select: none;\n -o-text-overflow: ellipsis;\n text-overflow: ellipsis;\n white-space: nowrap;\n overflow: hidden;\n padding: 0 1.16rem;\n font-size: 12px;\n line-height: 2rem;\n letter-spacing: 1px;\n color: #c6c8c8;\n text-shadow: 0 -1px rgba(0,0,0,0.69);\n vertical-align: top;\n background-color: #595b5b;\n -webkit-box-shadow: inset 0 1px rgba(255,255,255,0.12);\n box-shadow: inset 0 1px rgba(255,255,255,0.12);\n border: 1px solid rgba(0,0,0,0.36);\n -webkit-border-radius: 3px;\n border-radius: 3px;\n}\n.topcoat-button:active,\n.topcoat-button.is-active,\n.topcoat-button--large:active,\n.topcoat-button--large.is-active {\n background-color: #404141;\n -webkit-box-shadow: inset 0 1px rgba(0,0,0,0.18);\n box-shadow: inset 0 1px rgba(0,0,0,0.18);\n}\n.topcoat-button:disabled,\n.topcoat-button.is-disabled {\n opacity: 0.3;\n cursor: default;\n pointer-events: none;\n}\n"
},
{
"name": "Quiet Button",
"slug": "quiet-button",
"details": ":active - Quiet button active state\n.is-active - Simulates active state for a quiet button on touch interfaces\n:disabled - Disabled state\n.is-disabled - Simulates disabled state",
"markup": "<a class=\"topcoat-button--quiet\">Button</a>\n<a class=\"topcoat-button--quiet is-active\">Button</a>\n<a class=\"topcoat-button--quiet is-disabled\">Button</a>",
"css": ".topcoat-button--quiet {\n background: transparent;\n border: 1px solid transparent;\n -webkit-box-shadow: none;\n box-shadow: none;\n}\n.topcoat-button--quiet:active,\n.topcoat-button--quiet.is-active,\n.topcoat-button--large--quiet:active,\n.topcoat-button--large--quiet.is-active {\n color: #c6c8c8;\n text-shadow: 0 -1px rgba(0,0,0,0.69);\n background-color: #404141;\n border: 1px solid rgba(0,0,0,0.36);\n -webkit-box-shadow: inset 0 1px rgba(0,0,0,0.18);\n box-shadow: inset 0 1px rgba(0,0,0,0.18);\n}\n.topcoat-button--quiet:disabled,\n.topcoat-button--quiet.is-disabled {\n opacity: 0.3;\n cursor: default;\n pointer-events: none;\n}\n"
}
]
}
Nav Object
The 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
- else
li: a(href=item.url)=item.text
Project Object
The 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).
title=project.title
TemplateData Object
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.