Templates

Templates define the actual structure of the page - they’re basically just HTML with YAML placeholders built in. When a build starts, it looks for a template to combine with data in the build config to generate the final HTML page. To understand this better, chec out the Getting Started guide.

Using built-in templates

There are a few built-in templates that come with the application. You can find them in the Built-In Templates section of the documentation.

Creating a Template

To add your own template, create a directory for it in the custom templates directory (/config/templates/ when running in Docker), containing an index.html:

/config/templates/
└── my-template/
    ├── index.html       # required: a Go template
    └── metadata.yaml    # optional: description and documentation_url

Then set template: my-template in a build config. New templates are picked up when the web UI is loaded; the Add Template page in the web UI shows the exact directory being used.

A custom template with the same name as a built-in template takes priority over it, so you can also copy a built-in template into the custom templates directory and adapt it.

The custom templates directory can be changed with the STENCILBOX_TEMPLATES_DIR environment variable. When StencilBox is started with -configdir, <configdir>/templates is also searched.

To share additional files such as stylesheets or scripts between sites, keep them in a Git repository and reference it from your build config. See Custom Repos for more information.

Built-in template variables

Every build injects these variables so any template can use them:

Variable

Description

{{ .webuiUrl }}

URL of the StencilBox web UI for the build config that produced this page. Root-relative by default (/webui/build-config/<name>). Set STENCILBOX_WEBUI_URL_BASE when the built site is hosted on a different origin than StencilBox.

{{ .version }}

StencilBox version that ran the build.

{{ .buildDate }}

Build timestamp in RFC 3339 format.

{{ .buildDateFormatted }}

Human-readable build timestamp.

{{ .buildconfig }}

The build config object (Name, Template, OutputDir, and other fields).

Template hooks

Templates can define "hooks" - these are special placeholders that allow you to insert custom HTML or JavaScript into specific parts of the template. This is useful for adding custom functionality or styling to your pages without having to modify the entire template.

When you add a repo in your build config, StencilBox will look for "hooks" when building the page. If it finds any, it will replace them with the content you provide in your build config.

The following hooks are available:

  • {{head}} - Inserts content into the <head> section of the HTML document. This is useful for adding custom stylesheets or meta tags.

  • {{body}} - Inserts content immediately after the opening <body> tag. This is useful for adding elements that should appear at the very top of the page.