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:
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.
<!doctype html>
<html lang=en>
<head>
<meta charset=utf-8>
<title>{{ title }}</title>
<style>{{ style }}</style>
</head>
<body class="ourbigbook">
{{ body }}
</body>
</html>
Defined variables:
body
: the rendered bodydir_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 repositorygithub_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 yourourbigbook.json
:then you can use media from that repository with:"media-providers": { "github": { "remote": "mygithubusername/media" },
<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 IDmyid
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/135html_index
:/index.html
for local renders, empty for server rendersinput_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:README.bigbwith split header conversion, the value of= John Smith's homepage == Mathematics
is_root_relpath
would be:index.html
: truesplit.html
: truemathematics.html
: false
root_page
: relative path to the toplevel page, e.g. eitherindex.html
,../index.html
locally or./
,../
on server oriented rendereingroot_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 CSSmain.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 subdirectorymysubdir/myfile.html
, OurBigBook will set:giving the desired:root_relpath=../
<link rel="stylesheet" type="text/css" href="../main.css">
And if the output path were instead justmyohterfile.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/135raw_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 toraw_relpath
, but link to the_file
output directory insteadstyle
: default OurBigBook stylesheetstitle
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.