Crowbook User Guide 0.14.1

« 4. Markdown format

Chapter 5
Templates

Crowbook allows the user to specify a number of templates.^[4]

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.

5.1. Create and edit template

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

--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}}}^[5] 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.

Syntax in LaTeX

Since LaTeX already uses a lot of curly brackets, the default template sets an altenative syntax to access variables, with <<&foo>>^[6]:

\title{<<&title>>}
\author{<<&author>>}
<<#has_date>>\date{<<&date>>}<</has_date>

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 and epub.css.add allow to specify some LaTeX or CSS code directly in the book configuration file. This code will be added respectively to tex.template, html.css or epub.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, allowing to redefine commands.
• 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, while rendering.part.template does the same for part. These are used only for text-only output, such as in the TOC. html.chapter.template and html.part.template allow to change the HTML formatting for parts and chapters. These options should probably only be used if you know what you’re doing, as they can break the document. If you only need to change the name of chapters or parts, use rendering.part and rendering.chapter instead.

5.3. List of accessible variables

Metadata

For every template, Crowbook exports all of the metadata:

• author;
• title;
• subtitle;
• lang;
• subject;
• description;
• license;
• version;
• date;
• any option metadata.foo defined in the book configuration file will also be exported as metadata_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:

Template-dependent values

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

6. Proofreading with Crowbook »