Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

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.

Default Templates

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
    {{ 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.

Section Example

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

Section1: #structure is based on the actual yaml
  Item1: value0
  Item2: value1
    - 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     |

Generating content for Hugo websites

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