Select a custom Liquid template file for the output.
If not given, this option defaults to the value of template, which if not given defaults to ourbigbook.liquid.html.
The repository of this documentation for example has a sample ourbigbook.liquid.html at: ourbigbook.liquid.html.
If no template is present, the default template at one point was:
<!doctype html>
<html lang=en>
<meta charset=utf-8>
<title>{{ title }}</title>
<style>{{ style }}</style>
<body class="ourbigbook">
{{ body }}
This will get out of sync sooner or later with the code, but this should still serve as a good base example for this documentation.
Defined variables:
  • body: the rendered body
  • dir_relpath: relative path from the rendered output to the _dir directory. Sample usage to link to the root directory listing:
    <div><a href="{{ dir_relpath }}{{ html_index }}">Website source code</a></div>
  • git_sha: SHA of the latest git commit of the source code if in a git repository
  • github_prefix: this variable is set only if if the "github" media provider. It points to the URL prefix of the provider, e.g. if you have in your ourbigbook.json:
    "media-providers": {
      "github": {
        "remote": "mygithubusername/media"
    then you can use media from that repository with:
    <img src="image/x-icon" href="{{ github_prefix }}/myimage.jpg" />
  • html_ext: .html for local renders, empty for server renders.
    So e.g. to link to an ID myid you can use:
    <a href="{{ root_relpath }}myid{{ html_ext }}">
    This will ideally be replaced with a more generic link to arbitrary ID mechnism at some point: github.com/ourbigbook/ourbigbook/issues/135
  • html_index: /index.html for local renders, empty for server renders
  • input_path: path to the OurBigBook Markup source file relative to the project toplevel directory that generated this output, e.g. path/to/myfile.bigb
    May be an empty string in the case of autogenerated sources, notably automatic directory listings, so you should always check for that with something like:
    {% if input_path != "" %}
    <div>Source code for this page: <a href="{{ raw_relpath }}/{{ input_path }}">{{ input_path }}</a></div>
    {% endif %}
  • is_root_relpath. Boolean. True if the toplevel being rendered on this output file is the the index article. E.g. in:
    = John Smith's homepage
    == Mathematics
    with split header conversion, the value of is_root_relpath would be:
    • index.html: true
    • split.html: true
    • mathematics.html: false
  • root_page: relative path to the toplevel page, e.g. either index.html, ../index.html locally or ./, ../ on server oriented rendereing
  • root_relpath: relative path from the rendered output to the toplevel directory.
    This allows for toplevel resources like CSS to be found seamlessly form inside subdirectories, specially when rendering locally.
    For example, for the toplevel CSS main.css which is generated from main.scss, we can use:
    <link rel="stylesheet" type="text/css" href="{{ root_relpath }}main.css">
    Then, when a file is locally, for example under a subdirectory mysubdir/myfile.html, OurBigBook will set:
    giving the desired:
    <link rel="stylesheet" type="text/css" href="../main.css">
    And if the output path were instead just myohterfile.html, root_relpath expands to an empty string, giving again the correct:
    <link rel="stylesheet" type="text/css" href="main.css">
    This will ideally be replaced with a more generic link to arbitrary ID mechnism at some point: github.com/ourbigbook/ourbigbook/issues/135
  • raw_relpath: relative path from the rendered output to the _raw directory. Should be used to prefix all non-OurBigBook Markup output resources, which is the directory where such files are placed during conversion, e.g.
    <link rel="shortcut icon" href="{{ raw_relpath }}/logo.svg" />
  • file_relpath: similar to raw_relpath, but link to the _file output directory instead
  • style: default OurBigBook stylesheets
  • title
We pick Liquid because it is server-side safe: if we ever some day offer a compilation service, Liquid is designed to prevent arbitrary code execution and infinite loops in templates.


  1. OurBigBook CLI options
  2. OurBigBook CLI
  3. OurBigBook Project