Pug-doc
Pug-doc is a Pug documentation generator. It takes Pug files as input, looks for comments flagged with @pugdoc
and puts its contents in an output JSON file. It looks for the immediate next pug code block for output.
This package does not provide a styled interface for the documentation itself. Use Discodip for HTML output of all the examples, which can be used however you like.
You could also use pug-doc-html or pug-doc-markdown for human readable docs. Optionally use pug-doc-faucet for prettier terminal reporting.
Usage
Use the keyword @pugdoc
to flag unbuffered block comments inside your pug files. Comments should be written in properly formatted YAML format.
//- @pugdoc
name: my pugdoc
description: this is a description for my pug doc
beep: boop
foo: faa
see test/fixtures for examples.
HTML Output
The immediate next Pug code block after the comment will be compiled to HTML output. If you need to capture multiple blocks, see Capture multiple blocks
//- @pugdoc
name: some-node
div.this-is-output-for-pug-doc
div.this-isnt
Mixins
Optionally provide mixin arguments, attributes and example calls. If no examples are given, mixins will not be executed, so no output will be generated.
Arguments and attributes follow the jsdoc param syntax.
//- @pugdoc
name: my mixin
description: this is my mixin documentation
arguments:
- {string} arg1 - this is the description of arg1
- {number} arg2 - this is the description of arg2
attributes:
- {string} attr1 - this is the description of attr1
- {number} attr2 - this is the description of attr2
examples:
- +myMixin('foo', 1)
- +myMixin('faa', 2, attr1='foo', attr2='faa')
-
name: My mixin
description: this is my subexample
examples:
- |
+myMixin('beep', 3)
mixin myMixin(arg1, arg2)
div this is a mixin #{arg1} #{arg2} #{attr1} #{attr2}
Examples
You can add an example or multiple examples with the example
or examples
keyword, where the former is a YAML string and the latter a YAML list. The block
flag will be replaced by the captured block.
For documenting mixins the use of examples is recommended, since mixins will not be executed if no examples are given. For other pug blocks, examples are optional and can be used to add extra context (e.g. a parent div with styling).
single example
//- @pugdoc
name: example
example: |
div.example(style="max-width: 300px")
block
p this is my example
unnamed examples
//- @pugdoc
name: example
examples:
- |
div.example
block
- |
div.example
block
p this is my example
If an object is found inside the examples list, two things will happen. The subexample is 1) rendered and appended to the rest of the examples and 2) added to a list of fragments. This way a complete, rendered HTML example will be available, while also keeping the named subexamples intact.
named examples and combined example
//- @pugdoc
name: example
examples:
-
name: Subexample 1
example: |
div.example1
block
-
name: Subexample 2
example: |
div.example2
block
p this is my example
The behavior of combining examples into 1 can be turned of by setting example: false
.
only named examples
//- @pugdoc
name: example
example: false
examples:
-
name: Subexample 1
example: |
div.example1
block
-
name: Subexample 2
example: |
div.example2
block
p this is my example
beforeEach
//- @pugdoc
name: example
beforeEach: |
include ./my-mixin
examples:
-
name: Example 1
example: +my-mixin(1)
-
name: Example 2
example: +my-mixin(2)
-
name: Example 2
beforeEach:
example: +my-mixin(3) // ‹- error: my-mixin is undefined
Locals
Pug locals can be also be passed.
//- @pugdoc
name: tag
locals:
foo: foo
div #{foo}
Capture multiple blocks
The capture
keyword specifies how many blocks after the comment will be returned. Use capture: all
to capture the rest of the document. Use capture: section
to capture all items until the next pugdoc tag.
//- @pugdoc
name: tag
capture: 3
div 1
div 2
div 3
div nope
div nope
Keywords
-
name
used as an id -
description
provide context -
arguments
for mixin arguments. -
attributes
for (mixin) attributes. -
locals
for template locals. -
beforeEach
(string) add pug code before each example -
afterEach
(string) add pug code after each example -
example
- (string) for example mixin call or example block, or
- (false) to prevent rendering of master example combining all examples
-
examples
(list) for example mixin calls or example blocks examples.name
examples.description
-
examples.example
(string) -
examples.examples
(list) -
examples.beforeEach
(string) overwrite beforeEach for single example -
examples.afterEach
(string) overwrite afterEach for single example -
capture
for the number of code blocks to be captured-
all
: the rest of the document until it meets a lower indent -
section
: the rest of the document until it meets a lower indent or a new pugdoc comment -
number
: the exact positive number of blocks
-
How to use
npm install pug-doc
const pugDoc = require('pug-doc');
pugDoc({
input: '**/*.pug',
output: 'anything.json',
complete: function(){},
locals: {
myTemplateLocal: 'foo'
}
});
Caveats
Mixin dependencies
Mixins are standalone blocks, so you need to include any dependencies inside the mixin.
include ../mixin1.pug
//- @pugdoc
name: mixin2
example: +mixin2
mixin mixin2
+mixin1
Will throw something like TypeError: pug_mixins.mixin1 is not a function on line x
. Instead you need to do the include inside the mixin,
mixin mixin2
include ../mixin1.pug
+mixin1
+mixin2
or include it inside the example
//- @pugdoc
name: mixin2
example: |
include ../mixin1.pug
+mixin2
mixin mixin2
+mixin1
Command line
Optionally use it through the command line.
pug-doc input.pug
pug-doc input.pug --output output.json
pug-doc "**/*.pug" --output output.json
Output file
Output will look something like this.
[
{
"meta": {
"name": "foo",
"description": "foo description"
},
"file": "file.pug",
"source": "// foo",
"output": "<!-- foo-->"
}
]