Custom Repos

StencilBox comes with a few built-in templates and a simple theme. However you may want to use a different theme, inject content into templates (via hooks), use custom icons, or even create your own templates. This is where custom repos come in.

Custom repos are simply Git repositories that contain templates, assets, or other content that you want to use in your StencilBox builds. You can host these repositories anywhere - GitHub, GitLab, Bitbucket, or even a self-hosted Git server.

To use a custom repo, you need to add it to your build config. See the build config below for an example:

name: My sidebar of apps

template: iframe-sidebar

outputdir: sidebar

repos:
  - url: https://github.com/jamesread/StencilBox-custom-repo-example.git
	timeout: 60 # smaller repo, should be quick to download

datafiles:
  links: data/sidebar-links.yaml

In the example above we’re adding a custom repo that contains a custom template and some hook files. When Built, the page looks like this - a green theme background, and a custom content block on the page too;

Custom repo example

Using repos during builds

When you add a repo in your build config, StencilBox will clone the repository to a temporary location during the build process. How these repos are used depends on the content;

  • If the repo contains body.html or head.html files, these are treated as "hooks" and will be injected directly into the template at the appropriate hook locations. These can contain any valid HTML (including <script> tags for JavaScript, or <style> tags for CSS).

  • If the repo contains a template, then you can reference that template in your build config by setting the template field to the path of the repo. eg: repos/my-custom-repo.

Custom repos can contain basically anything you want.