Working with Templates

Yamldocs works by default with Stencil templates, a simple templating library that is often used to bootstrap files and has no external dependencies.

There are two templates included within the application’s /templates folder:

• reference_page.tpl
• reference_page_section.tpl

These templates are used by the DefaultBuilder to build the final markdown through the built-in build commands. If you want to customize the templates, you need to overwrite them. Set the templates in a folder inside your app and set up a templatesDir parameter in your yamldocs.yaml configuration. It’s worth noting that the use of Stencil templates is not mandatory when creating custom builders.

The reference_page.tpl is the parent template that renders the final markdown page result. For instance, if you need to include a front-matter to your markdown, this is most probably the place where it should go.

The reference_page_section.tpl is a sub-template used to render each section of the generated page.

Here’s the content of each file for reference:

    ## {{ title }}
    {{ description }}
    
    {{ content }}

• {{ title }} - high-level title of the document. When no metadata is defined, this is typically the name of the file without the extension.
• {{ description }} - can be defined via metadata or auto-generated as “{{ title }} reference docs”.
• {{ content }} - content generated by the builder, which may consist of multiple sections.

    ## {{ item }}
    {{ description }}
    
    ### Reference
    
    {{ reference_table }}
    
    ### Example
    
    ```yaml
    {{ example }}
    ```
    
    {{ notes }}

• {{ item }} - section title. Can be defined via metadata or auto-generated from yaml node name.
• {{ description }} - section description. Defined via metadata.
• {{ reerence_table }} - the reference table is generated from second-level nodes in the yaml file.
• {{ example }} - optional, based on metadata only.
• {{ notes }} - optional, based on metadata only.

With the default builder, a section defined by the following yaml…

Section1: #structure is based on the actual yaml
  Item1: value0
  Item2: value1
  Item3:
    - value12
    - value13
  Item4: value2

… is rendered as the following markdown:

    ## Section1
    
    ### Reference
    
    | Directive | Expects             |
    |-----------|---------------------|
    | Item1     | (String) value0     |
    | Item2     | (String) value1     |
    | Item3     | (Array)             |
    | Item4     | (String) value2     |

To generate content for a Hugo website, you’ll want to overwrite the default reference_page.tpl to include a front-matter section.

What goes on the front-matter often depends on the theme and layouts used, which can have custom variables. A simple example would be:

    ---
    title: "{{ title }}"
    description: "{{ description }}"
    weight: 1
    ---

    {{ description }}
    
    {{ content }}