11 KiB
Templates
Crowbook allows the user to specify a number of templates.1
Each of this template can be overriden by a custom one, by setting e.g.:
html.css: my_template.css
in the book configuration file. The templates that you are most susceptible to modify are the following:
html.css
: stylesheet for HTML output;epub.css
: stylesheet for EPUB output;tex.template
: template of a LaTeX file.
Create and edit template
Except for inline templates, which are set directly in the book configuration file:
rendering.chapter.template: "{{{loc_chapter}}} {{{number}}}: {{{chapter_title}}}"
most templates must be in a separate file:
tex.template: my_template.tex
--print-template
The easiest way to create a new template is to start with the default one. In order to do so, you can use the --print-template
argument:
$ crowbook --print-template tex.template > my_template.tex
In order to get the chapter.xhtml
template for EPUB3, you'll also have to use --set epub.version 3
:
$ crowbook --print-template epub.chapter.xhtml --set epub.version 3 > my_epub3_template.xhtml
Mustache syntax
Crowbook uses rust-mustache as its templating engine, which allows to use Mustache syntax in the templates.
It mainly boils down to using {{{foo}}}
2 to insert the value of
variable foo
in the document:
<h1 class = "title" >{{{title}}}<h1>
<h2 class = "author">{{{author}}}</h2>
Mustache also provides the possibility of checking whether a variable is set:
{{#foo}}
Foo exists
{{/foo}}
{{^foo}}
Foo does not exist
{{^foo}}
Crowbook uses this and sets some variables to true
to allow
templates to conditionally include some portions. E.g., in html.css
:
{{#lang_fr}}
/* Make list displays '–' instead of bullets */
ul li {
list-style-type: '–';
padding-left: .5em;
}
{{/lang_fr}}
In this case, Crowbook sets a variable whose name is equal to
lang_foo
to true
, allowing to have different styles for some
elements according to the language.
For more information about Mustache syntax, see Mustache manual.
Syntax in LaTeX
Since LaTeX already uses a lot of curly brackets, the default template
sets an altenative syntax to access variables, with <<&foo>>
3:
\title{<<&title>>}
\author{<<&author>>}
<<#has_date>>\date{<<&date>>}<</has_date>
- escaping is already done by Crowbook before setting variable content;
- escaping HTML in a LaTeX document won't probably look good.
List of templates
html.js
The javascript file used by both the standalone HTML renderer and the multiple files HTML renderer.
This is not currently an actual template, just a plain
javascript file which cannot contain mustache
tags.
html.css
The main CSS file used by both the standalone HTML renderer and the multiple files HTML renderer.
html.css.colours
A CSS file containing only colour settings. Used by html.css
.
This is not currently an actual template, just a plain
CSS file which cannot contain mustache
tags.
html.css.print
An additional CSS file used by both the standalone HTML renderer and
the multiple files HTML renderer. Its purpose is to provide CSS
instructions for printing (i.e., when the user clicks the print
button in her browser).
This is not currently an actual template, just a plain
CSS file which cannot contain mustache
tags.
html.highlight.js
A javascript file used by both HTML renderers to highlight codes in code blocks. It should be a variant of highlight.js.
This is not an actual template, just a plain javascript file.
html.highlight.css
A CSS file used by both HTML renderers to set the theme of highlight.js. It should, though, be an highlight.js theme.
This is not an actual template, just a plain CSS file.
html.standalone.js
A javascript file used only by the standalone HTML renderer. Its main
purpose is to handle the displaying of a single chapter at a time when
one_chapter
is set to true.
html.standalone.template
The main HTML template for standalone HTML renderer.
html.dir.template
The main HTML template for multiple files HTML renderer.
tex.template
The main (and currently only) template used by the LaTeX renderer.
epub.chapter.xhtml
This template is the main template used by the Epub renderer. It contains the XHTML template that will be used for each chapter.
epub.css
This template is used by the Epub renderer and contains the style sheet.
Inline templates
Crowbook also has some inline templates, that are set in the book configuration file:
tex.template.add
,html.css.add
andepub.css.add
allow to specify some LaTeX or CSS code directly in the book configuration file. This code will be added respectively totex.template
,html.css
orepub.css
template. For CSS templates, this code is inserted at the end of the template (allowing to redefine rules that are set by the template); for the LaTeX template, the code is inserted at the end of the preambule, just before the\begin{document}
tag.rendering.inline_toc.name
sets the name of the inline table of content, if it is displayed. By default, is is set to{{{loc_toc}}}
, that is, a localised version of "Table of Contents".rendering.chapter.template
sets the naming scheme for chapters, whilerendering.part.template
does the same for part.
List of accessible variables
Metadata
For every template, Crowbook exports all of the metadata:
author
;title
;lang
;subject
;description
;license
;version
;date
;- any option
metadata.foo
defined in the book configuration file will also be exported asmetadata_foo
.
These metadata can contain Markdown, which will be rendered. E.g.,
setting date: "20th of **september**"
will render september
in
bold, using <b>
tag for HTML or \textbf
for LaTeX. If you need to
use these data in places that don't support formatted text (e.g. in
meta tags), you can use the raw content by accessing xxx_raw
instead
(e.g., author_raw
, title_raw
, ...). (Note that the content of the
raw metadata is not HTML-escaped, so in this case you might want to
use {{xxx_raw}}
instead of {{{xxx_raw}}}
.)
For each metadata foo
that is set, Crowbook also inserts a has_foo
bool set to true. This allows to use Mustache's section for some logic, e.g.:
{{{title}}}
{{#has_version}}, version {{{version}}}{{/has_version}}
will avoid rendering ", version" when version
is not set.
Localisation strings
For all templates, Crowbook also exports some localisation strings loc_foo
. They currently include:
Localisation key | Value in english |
---|---|
loc_toc |
Table of contents |
loc_cover |
Cover |
loc_title |
Title |
loc_chapter |
Chapter |
loc_part |
Part |
loc_notes |
Notes |
loc_display_all |
Display all chapters |
loc_display_one |
Display one chapter |
Template-dependent values
Crowbook also exports some additional fields for some templates, see below.
Mustache tag | Value | Available in... |
---|---|---|
content |
A rendered version of the book or chapter's content | html.standalone.template , html.dir.template , tex.template , epub.chapter.xhtml |
toc |
A rendered version of the table of contents | html.standalone.template , html.dir.template |
has_toc |
Set to true if the table of contents is not empty |
html.standalone.template |
colours |
The content of html.css.colours |
html.css |
footer |
The content of html.footer |
html.standalone.template , html.dir.template |
header |
The content of html.header |
html.standalone.template , html.dirtemplate |
script |
The javascript file for this HTML document | html.standalone.template , html.dir.template |
style |
The CSS file for this HTML document, that is, a rendered version of html.css |
html.standalone.template |
A variable whose name corresponds to lang in book options (e.g. lang_en if lang is set to "en", lang_fr if it is set to "fr", ...) |
true |
html.css , epub.css |
chapter_title |
The title of current chapter | html.dir.template , epub.chapter.xhtml , rendering.chapter.template |
chapter_title_raw |
The title of current chapter (raw text without HTML formatting) | html.dir.template , epub.chapter.xhtml , rendering.chapter.template |
highlight_code |
True if html.highlight_code is true |
html.standalone.template , html.dir.template |
highlight_css |
The content of html.highlight.css |
html.standalone.template |
highlight_js |
The base64-encoded content of html.highlight.js |
html.standalone.tempate |
common_script |
The content of html.js |
html.single.js |
one_chapter |
True if html.standalone.one_chapter is true, else not present |
html.standalone.template , html.standalone.js |
book.svg |
The base64-encoded image of the button to display all chapters | html.standalone.js , html.standalone.template |
pages.svg |
The base64-encoded image of the button to display one chapter at a time | html.standalone.js , html.standalone.template |
favicon |
The <link rel = "icon" ...> tag if html.icon is set |
html.standalone.template , html.dir.template |
menu_svg |
The base64-encoded image of the hamburger menu image | html.standalone.template |
prev_chapter |
Title and a link of previous chapter | html.dir.template |
next_chapter |
Title and a link of nexts chapter | html.dir.template |
class |
The content of tex.class |
tex.template |
book |
True if tex.class is book , not set else |
tex.template |
tex_lang |
The babel equivalent of lang |
tex.template |
tex_title |
Set to true to run \maketitle |
tex.template |
tex_size |
The font size to pass to the LaTeX class | tex.template |
has_tex_size |
Set to true if tex_size is set |
tex.template |
initials |
True if rendering.initials is true, not set else |
tex.template |
additional_code |
Set to the content of tex.template.add , html.css.add or epub.css.add |
tex.template , html.css , epub.css |
-
Some of them, though, are not "real" templates, they are just files that are inserted, but can't contain mustache tags. This will probably evolve in future versions. ↩︎
-
Mustache also provides the
{{foo}}
variant, which HTML-escapes the content of the variable. You should not use this, as Crowbook already renders and correctly escapes the variables it sets for use in templates. ↩︎ -
<<foo>>
might also work, but the ampersand is required to prevent mustache HTML-escaping the value. This is not good because: ↩︎