You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+63-28Lines changed: 63 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,13 @@
2
2
3
3
---
4
4
5
-
A tool for generating usage and styles guides for html components using css block comments.
5
+
A tool for generating usage and styles guides for html components using css
6
+
block comments.
6
7
7
8
## Quick Intro
8
9
9
-
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.
10
+
By adding a Topdoc block to your css you can describe an html/css component and
11
+
that information can be used to generate a styleguide.
10
12
11
13
Here's an example component:
12
14
@@ -32,19 +34,25 @@ tags:
32
34
33
35
### Why create another css block comment format?
34
36
35
-
Topdoc was originally created for [Topcoat](http://topcoat.io) 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.
37
+
Topdoc was originally created for [Topcoat](http://topcoat.io) and the one
38
+
feature missing from other generators was support for any and all custom
39
+
properties. Topdoc is extremely tolerant of custom properties, it just passes
40
+
them to the template which defines what to do with it.
36
41
37
-
The only required properties are `name` and `markup`, other than that, use whatever you need.
42
+
The only required properties are `name` and `markup`, other than that, use
43
+
whatever you need.
38
44
39
45
## Installation
40
46
41
-
Install with npm. It's meant to be command line tool, so you probably want to install it globally (with `-g`).
47
+
Install with npm. It's meant to be command line tool, so you probably want to
48
+
install it globally (with `-g`).
42
49
43
50
```sh
44
51
npm install -g topdoc
45
52
```
46
53
47
-
You can also use it as a npm script without install it globally. Super helpful for automating your styleguide building:
54
+
You can also use it as a npm script without install it globally. Super helpful
55
+
for automating your styleguide building:
48
56
49
57
```sh
50
58
npm install --save-dev topdoc
@@ -68,7 +76,8 @@ npm run docs
68
76
69
77
### Comment Format
70
78
71
-
Topdoc uses [PostCSS](http://postcss.org/) to divide asunder your css document and find all the relevant component information.
79
+
Topdoc uses [PostCSS](http://postcss.org/) to divide asunder your css document
80
+
and find all the relevant component information.
72
81
73
82
Below is an example of a Topdoc comment.
74
83
@@ -104,18 +113,25 @@ blarg: very true
104
113
}
105
114
```
106
115
107
-
Topdoc comments are identified by the `topdoc` keyword on the first comment line.
116
+
Topdoc comments are identified by the `topdoc` keyword on the first comment
117
+
line.
108
118
109
119
The rest of the data uses a [YAML](http://www.yaml.org/) friendly syntax.
110
120
111
121
The fields can be in any order, but this is a good example for consistency sake.
112
122
113
123
The following are recommend and/or required fields:
114
124
115
-
*`name` (required): The full name of the component. Feel free to use spaces, punctuation, etc (name: Sir Button III, esq.)
116
-
*`description`: Something more descriptive then the title alone.
117
-
*`modifiers`: These can be pseudo classes, or addition rules applied to the component. This must be a [YAML mapping](http://yaml4r.sourceforge.net/doc/page/collections_in_yaml.htm) (`*modifier*:*description*`) which becomes a js hash
118
-
*`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.
125
+
-`name` (required): The full name of the component. Feel free to use spaces,
126
+
punctuation, etc (name: Sir Button III, esq.)
127
+
-`description`: Something more descriptive then the title alone.
128
+
-`modifiers`: These can be pseudo classes, or addition rules applied to the
(`*modifier*:*description*`) which becomes a js hash
132
+
-`markup` (required): This is the magic; it's the html that will be used to
133
+
display the component in the docs. As most markup fields are long, make sure
134
+
to use the `|` for multiline values.
119
135
```css
120
136
/* topdoc
121
137
name: Button
@@ -125,16 +141,23 @@ The following are recommend and/or required fields:
125
141
<a class="topcoat-button is-disabled">Button</a>
126
142
*/
127
143
```
128
-
*`tags`: Just some obligatory metadata.
129
-
*`blarg`: Since Topdoc uses a flexible YAML syntax, feel free to add any additional custom data you might need for your template.
144
+
-`tags`: Just some obligatory metadata.
145
+
-`blarg`: Since Topdoc uses a flexible YAML syntax, feel free to add any
146
+
additional custom data you might need for your template.
130
147
131
148
### Components
132
149
133
-
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.
150
+
Topdoc assumes everything between two Topdoc comments, and everything after the
151
+
last Topdoc comment, is a component. Put anything that isn't a component
152
+
(general styles) above the first Topdoc comment.
134
153
135
-
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.
154
+
However, the idea of css components is pretty loose because it is rare to have
155
+
all the required styles for a component in one place.
136
156
137
-
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.
157
+
Originally Topdoc was designed to split up the css into components to then use
158
+
that css in the styleguild to show as a snippet, but honestly that snippet
159
+
wasn't enough to make the component by itself so it really is only interesting
160
+
as reference.
138
161
139
162
## Help
140
163
@@ -168,31 +191,33 @@ $ topdoc --help
168
191
169
192
### Source
170
193
171
-
Specify a source directory with `-s` or `--source`. Defaults to `src/`.
194
+
Specify a source directory with `-s` or `--source`. Defaults to `src/`.
172
195
173
196
```bash
174
197
topdoc -s release/css/
175
198
```
176
199
177
200
### Destination
178
201
179
-
Specify a destination with `-d` or `--destination`. Defaults to `docs/`.
202
+
Specify a destination with `-d` or `--destination`. Defaults to `docs/`.
180
203
181
204
```bash
182
205
topdoc -d topdocs/
183
206
```
184
207
185
208
### Template
186
209
187
-
Specify a template with `-t` or `--template`. A default template is included in Topdoc if one is not provided.
210
+
Specify a template with `-t` or `--template`. A default template is included in
211
+
Topdoc if one is not provided.
188
212
189
213
The template can be a single [jade](https://github.com/visionmedia/jade) file:
190
214
191
215
```bash
192
216
topdoc -t template/template.jade
193
217
```
194
218
195
-
or a directory (it will duplicate the whole template directory and look forindex.jadein the template folder provided):
219
+
or a directory (it will duplicate the whole template directory and look for
220
+
index.jade in the template folder provided):
196
221
197
222
```bash
198
223
topdoc -t /template
@@ -226,9 +251,13 @@ yeilds:
226
251
227
252
## `package.json` Configuration
228
253
229
-
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.
254
+
All the options can be configured in the package.json file. This is super
255
+
helpful if you are always using the same configuration. It will look in the
256
+
package.json file if it exists, but can be overridden by the command line
257
+
options.
230
258
231
-
Also, additional data can be passed through to the jade template. Below is an example:
259
+
Also, additional data can be passed through to the jade template. Below is an
260
+
example:
232
261
233
262
```json
234
263
{
@@ -249,7 +278,7 @@ Also, additional data can be passed through to the jade template. Below is an e
249
278
"download": {
250
279
"url": "#",
251
280
"label": "Download version 0.4"
252
-
},
281
+
},
253
282
"homeURL": "http://topcoat.io",
254
283
"siteNav": [
255
284
{
@@ -288,7 +317,8 @@ The jade template has data passed through by default:
288
317
289
318
### Document Object
290
319
291
-
The `document` object contains relevant information about just the current document being generated below is an example:
320
+
The `document` object contains relevant information about just the current
321
+
document being generated below is an example:
292
322
293
323
```json
294
324
{
@@ -318,7 +348,8 @@ The `document` object contains relevant information about just the current docum
318
348
319
349
### Nav Object
320
350
321
-
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.
351
+
The `nav` object contains names and urls to all the generated html files. In the
352
+
jade template this can utilized to create a navigation to the other pages.
322
353
323
354
```jade
324
355
nav.site: ul
@@ -331,12 +362,16 @@ nav.site: ul
331
362
332
363
### Project Object
333
364
334
-
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).
365
+
The `project` object contains relevant project information. Currently it only
366
+
contains the `title` property. (passed through the command line `-p` option, or
367
+
through the package.json information).
335
368
336
369
```jade
337
370
title=project.title
338
371
```
339
372
340
373
### TemplateData Object
341
374
342
-
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.
375
+
As mentioned above, additional data can be passed through to the template in the
376
+
package.json file. This is accessible in the template as the `templateData`
0 commit comments