OurBigBook
Select a custom Liquid template file for the output.
The recommended file name for this file is:
main.liquid.html
which is already ignored by default from the published output.
This repository has a sample main.liquid.html at: main.liquid.html.
If not given, the default template at one point was:
<!doctype html>
<html lang=en>
<head>
<meta charset=utf-8>
<title>{{ title }}</title>
<style>{{ style }}</style>
</head>
<body class="ourbigbook">
{{ body }}
</body>
</html>
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_replath: 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
  • 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 %}
  • root_page: relative path to the toplevel page, e.g. either index.html, ../index.html locally or ./, ../ on server oriented rendereing
  • root_replath: 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:
    root_relpath=../
    giving the desired:
    <link rel="stylesheet" type="text/css" href="../main.css">
    And if the output path were instead just myohterfile.html, root_replath 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_replath: 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" />
  • 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.

Ancestors