Numerous Problems Multiplied
    Have ideas to improve npm?Join in the discussion! »

    pug-doc

    2.23.0 • Public • Published

    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-->"
      }
    ]

    Install

    npm i pug-doc

    DownloadsWeekly Downloads

    117

    Version

    2.23.0

    License

    ISC

    Unpacked Size

    68.1 kB

    Total Files

    28

    Last publish

    Collaborators

    • avatar