Crowbook User Guide 0.15.0

« 4. Markdown format

Chapter 5
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:

Except for inline templates, which are set directly in the book configuration file:

# Template that modify how a chapter title is displayed
rendering.chapter.template: "{{{loc_chapter}}} {{{number}}}: {{{chapter_title}}}"

# CSS code added to default CSS templates (but don't override it)
html.css.add: "h1 { background-color: red; }"
epub.css.add: "h1 { background-color: gray; }"

# LaTeX code added to default LaTeX template (but doesn't override it)
template.tex.add: "\usepackage{libertineotf}"

most templates must be in a separate file:

tex.template: my_template.tex

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

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 the Mustache manual.

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>
  1. escaping is already done by Crowbook before setting variable content;

  2. escaping HTML in a LaTeX document won’t probably look good.

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.

The main CSS file used by both the standalone HTML renderer and the multiple files HTML renderer.

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.

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.

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.

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.

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.

The main HTML template for standalone HTML renderer.

The main HTML template for multiple files HTML renderer.

The main (and currently only) template used by the LaTeX renderer.

This template is the main template used by the Epub renderer. It contains the XHTML template that will be used for each chapter.

This template is used by the Epub renderer and contains the style sheet.

Crowbook also has some inline templates, that are set in the book configuration file:

For every template, Crowbook exports all of the metadata:

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.

For all templates, Crowbook also exports some localisation strings loc_foo. They currently include:

Localisation keyValue in english
loc_tocTable of contents
loc_coverCover
loc_titleTitle
loc_chapterChapter
loc_partPart
loc_notesNotes
loc_display_allDisplay all chapters
loc_display_oneDisplay one chapter

Crowbook also exports some additional fields for some templates, see below.

Mustache tagValueAvailable in...
contentA rendered version of the book or chapter’s contenthtml.standalone.template, html.dir.template, tex.template, epub.chapter.xhtml
tocA rendered version of the table of contentshtml.standalone.template, html.dir.template
has_tocSet to true if the table of contents is not emptyhtml.standalone.template
colorsThe content of html.css.colorshtml.css
footerThe content of html.footerhtml.standalone.template, html.dir.template
headerThe content of html.headerhtml.standalone.template, html.dirtemplate
scriptThe javascript file for this HTML documenthtml.standalone.template, html.dir.template
styleThe CSS file for this HTML document, that is, a rendered version of html.csshtml.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”, ...)truehtml.css, epub.css
chapter_titleThe title of current chapterhtml.dir.template, epub.chapter.xhtml, rendering.chapter.template
chapter_title_rawThe title of current chapter (raw text without HTML formatting)html.dir.template, epub.chapter.xhtml, rendering.chapter.template
json_dataContains structured data with book’s metadata in JSON-LD formathtml.standalone.template, html.dir.template
highlight_codeTrue if html.highlight_code is truehtml.standalone.template, html.dir.template
highlight_cssThe content of html.highlight.csshtml.standalone.template
highlight_jsThe base64-encoded content of html.highlight.jshtml.standalone.tempate
common_scriptThe content of html.jshtml.single.js
one_chapterTrue if html.standalone.one_chapter is true, else not presenthtml.standalone.template, html.standalone.js
book.svgThe base64-encoded image of the button to display all chaptershtml.standalone.js, html.standalone.template
pages.svgThe base64-encoded image of the button to display one chapter at a timehtml.standalone.js, html.standalone.template
faviconThe <link rel = "icon" ...> tag if html.icon is sethtml.standalone.template, html.dir.template
menu_svgThe base64-encoded image of the hamburger menu imagehtml.standalone.template
prev_chapterTitle and a link of previous chapterhtml.dir.template
next_chapterTitle and a link of nexts chapterhtml.dir.template
classThe content of tex.classtex.template
bookTrue if tex.class is book, not set elsetex.template
tex_langThe babel equivalent of langtex.template
tex_titleSet to true to run \maketitletex.template
tex_sizeThe font size to pass to the LaTeX classtex.template
has_tex_sizeSet to true if tex_size is settex.template
margin_left, margin_right, margin_top, margin_bottomThe margins of the documenttex.template
initialsTrue if rendering.initials is true, not set elsetex.template
additional_codeSet to the content of tex.template.add, html.css.add or epub.css.addtex.template, html.css, epub.css

6. Proofreading with Crowbook »