Crowbook User Guide 0.15.0

« 2. Arguments

Chapter 3
The configuration file

If you want to use Crowbook for your book, this configuration file is all you’ll have to add, beside the Markdown files containing the text of your book.

The format is not very complicated. This is an example of it:

# metadata
author: Joan Doe
title: Some book
lang: en

output: [html, pdf, epub]

# list of chapters
- preface.md
+ chapter_1.md
+ chapter_2.md
+ chapter_3.md
+ chapter_4.md
- epilogue.md

Basically, it is divided in two parts:

Lines starting with the # characters are comments and are discarded.

Sometimes, you only have one Markdown file and might not want to have a separate configuration file. In this case, you can specify options at the beginning of your Markdown file, using an inline YAML block, separated by two lines containing only ---:

---
author: Joan Doe
title: Some (short) book
lang: en

output: [html, pdf, epub]
---

# Some (short) book

The book content, formatted in Markdown.

This method only allows to set up options: you can’t include a list of chapters in this way, since the only “chapter” that will be included is this Markdown file itself.

You can then use

crowbook -s some_book.md

to generate output formats from this Markdown file.

By default (unless input.yaml_blocks is set to true), Crowboook will only read those inline blocks when it is runned with crowbook --single (or crowbook -s).

There are various options to include a Markdown file.

So a typical usage might look like this:

! copyright.md
- preface.md
0. chapter_0.md # We want to start at chapter 0 instead of 1
# Next chapters can be numbered automatically
+ chapter_1.md
+ chapter_2.md
...

There are two important things to note:

  1. you must not use quotes around the file names.

  2. the paths of these files are relative to the directory where your configuration file is. This means you can run crowbook books/my_trilogy/first_book/config.book without being in the book’s directory.

Also note that you don’t have to specify a title. This is because the title of the chapter is inferred from the Markdown document. To go back to our previous example:

+ chapter_1.md

does not specify a chapter title, because it will read it directly in chapter_1.md, e.g.:

# The day I was born #
...

Ideally, you should have one and only one level-one header (i.e. chapter title) in each Markdown file. If you have more than one, it might mess with the table of contents in some cases (e.g. for EPUB).

Parts are included using the @ character, followed by the same characters than for chapters:

@+ numbered_part.md
+ chapter_01.md
+ chapter_02.md
@- unnumbered_part.md
+ chapter_03.md
+ chapter_04.md
@42. part_with_number_42.md
+ chapter_05.md

However, you usually don’t really want to have a content directly below the part, only chapters (though it can be useful to add an introduction before the first chapter of this part), so there is also a more straighforward way to use parts, using only the @ character followed by the (markdown-formatted) title of this part:

@ Beginning
+ chapter_01.md
+ chapter_02.md
@ Middle
+ chapter_03.md
+ chapter_04.md
@ Appendix
- notes.md

With this shortcut, parts are always numbered.

If you write your book to be rendered by crowbook, it is better to have one Markdown file per chapter. It is, however, possible to work with divisions at lower levels. In order to properly include these files, you can use the following syntax:

-- section.md
--- subsection.md
---- subsubsection.md

Note that there isn’t different syntax for numbered or unnumbered sections/subsections: you can only change the numbering scheme at the chapter level.

When including those files, Crowbook will include them in the table of content as part of the previous chapter (or section for subsections, and so on). It will also adjust the header levels of the Markdown files, so, in the previous example, a level-1 header in section.md will be displayed as a level-2 header in the book, and a level-1 header in subsection.md as a level-3 header.

This can cause issues as only six levels of headers are supported; hence, if you include a level-5 header in subsubsection.md, it will cause an error.

The first part of the configuration file is dedicated to pass options to Crowbook. This is YAML syntax, so each line should be of the form key: value. Note that in most cases you don’t have to put string in quotes, e.g.:

title: My title

It is however possible (and sometimes necessary) to escape some characters using quotes around strings:

title: "My: title!"

It is possible to use multiline strings with >- and then indenting the lines that are part of the string:

title: >-
 A
 long
 title
author: Joan Doe

will set title to "A long title". See block literals in YAML for more information on the various way to insert multiline strings (which mostly change the way newlines will or won’t be inserted).

A final note on the syntax: all options must be set before the first chapter inclusion (that is, a line beginning with +, -, x. (where x is a number) or !).

Metadata are data about the book. Except for cover, which points to an image file, all its fields are strings. The main metadata are:

There are also additional metadata:

You can define your own metadata by starting an option name with metadata.foo.

All metadata are accessible from templates, see Templates.

The special import option allows you to include the options of another book configuration file. E.g., assuming that you want some common options to be applied to both foo.book and bar.book, you can create a common.book file:

author: Joan Doe
lang: en
license: "Copyright (C) Joan Doe. All rights reserved."

html.header: "[Joan Doe's website](http://joan-doe.com)"
tex.template: my_template.tex

You can then include this file in foo.book:

import: common.book
title: Foo

+ foo_01.md
+ foo_02.md

Or include it in bar.book, but override some of its features:

import: common.book
title: Bar
license: CC-BY-SA  # Override the license from common.book

+ bar_01.md

These options specify which files to generate.

Note that all file paths are relative to the directory where the configuration file is, not to the one where you run crowbook. So if you set:

output.epub: foo.epub

and run

$ crowbook some/dir/config.book

foo.epub will be generated in some/dir, not in your current directory.

Crowbook will try to generate each of the output.xxx files that are specified. That means that you’ll have to set at least one of those if you want a call to

$ crowbook my.book

to generate anything. (It’s still possible to generate a specific format, and only this one, by using the --to and --output argument on the command line).

Note that some formats depend on some commands being installed on your system. Most notably, Crowbook depends on LaTeX (xelatex by default, though you can specify another command to use with tex.command) to generate a PDF file, so PDF rendering won’t work if it is not installed on your system. Crowbook also uses the zip command to generate the EPUB and ODT files.

Current output options are:

(There are other output options for generating proofreading files, see Proofreading, and interactive fiction, see Interactive fiction.)

Setting output file names manually can be a bit tedious, and is not always necessary. You can also specify a list of output formats with the output option:

output: [pdf, epub, html]

This is similar to the alternative syntax for YAML list:

output:
  - pdf
  - epub
  - html

This option will set default output path for PDF, EPUB and HTML according to the book configuration file name. So, if your book is my_book.book (or my_book.md), it will generate my_book.pdf, my_book.html and my_book.epub.

You can also infer the output file name by specifying “auto” to e.g. output.html. The previous example is thus equivalent to

output.pdf: auto
output.epub: auto
output.html: auto

Additionally, the output.base_path option allows you to set where the output files will be written (relatively to the book configuration file). E.g.,

output.base_path: docs/book
output.epub: book.epub

will render the EPUB file in docs/book/book.epub.

Crowbook does its best to improve the typography of your text. Default settings should be good enough for most usages, but you can enable/disable specific options:

These options allow to configure the rendering; they are used (or at least should be) for all formats.

If your version of crowbook (as is the case for Windows builds) isn’t built with syntect support, it will default to none if you try to use it.

These options allow you to customize the HTML rendering (used both by the default HTML standalone renderer and the HTML multifile renderer):

There are a few options specific to the standalone HTML renderer (default, set with output.html):

These options allow you to customize the LaTeX renderer (and, thus, the generated PDF documents):

There are also options specific to the EPUB format:

These options allow to embed additional files for some formats (currently, only EPUB). This can be useful for embedding fonts.

A list of files or directories that should be added.

resources.files: [font1.otf, font2.otf]

It is also possible to specify a directory (or multiple directories). So if you have a fonts directories containing font1.otf and font2.otf,

resources.files: [fonts]

will be equivalent to:

resources.files: [fonts/font1.otf, fonts/font2.otf]

default: not set

This option determine where (in which directory), in the resulting document, those files will be copied. The default is data, so by default the resources.files in the first example above will search font1.otf and font2.otf in the same directory than the .book file, and will copy them to data/font1.otf and data/font2.otf in the EPUB file. This is therefore this last path that you should use if you want to access those files e.g. in a custom CSS stylesheet.

Note that if you pass directories to resources.files, the whole directory would be copied. So assuming fonts/ contains font1.otf and font2.otf

resources.files: [fonts]
resources.path: data

will copy these two files to data/fonts/font1.otf and data/fonts/font2.otf (and not data/font1.otf and data/font2.otf).

Similarly, the whole path of resources.files is copied, so

resources.files: [fonts/font1.otf, fonts/font2.otf]

will yield the same result.

default: data

Here is the complete list of options. You can always look at it by running crowbook --list-options or crowbook -l.

Note that these options have a type, which in most case should be pretty straightforward (a boolean can be true or false, an integer must be composed by a number, a string is, well, any string (note that you might need to use quotes if it includes some characters that may lead the YAML parser to read it as an array, an integer or a list), and a list of strings is a list containing only strings, see YAML syntax). The path type might puzzle you a bit, but it’s equivalent to a string, except Crowbook will consider it relatively to the book file. The template path type is just the path of a template. Metadata are just strings.

4. Markdown format »