25 KiB
The configuration file
If you want to use Crowbook for your book, this configuration file is all you'll have to add (assuming you already have the book in Markdown files; if you don't, you'll also have to write a book first, but that's besides the scope of this document).
The format is not very complicated. This is an example of it:
# metadata
author: Joan Doe
title: Some book
lang: en
output.html: some_book.html
# 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:
- a list of options, under the form
key: value
, following YAML syntax. - a list of Markdown files.
Lines starting with the #
characters are comments and are discarded.
Configuration in an inline YAML block (crowbook --single
)
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: some_book.html
---
# 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 --single 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 withcrowbook --single
(orcrowbook -s
).
The list of files
There are various options to include a Markdown file.
+ file_name.md
includes a numbered chapter.- file_name.md
includes an unnumbered chapter.! file_name.md
includes a chapter whose title won't be displayed (except in the table of contents); this is useful for e.g. including a copyright at the beginning or the book, or for short stories where there is only one chapter.42. file_name.md
specifies the number for a chapter.@
includes a part instead of a chapter.
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:
- you must not use quotes around the file names.
- the path 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
==================
...
You should have one and only one level-one header (i.e. chapter title) in each markdown file.
If you have more than one, Crowbook will print a warning and treat it as another chapter (numbered according to the scheme specified for including the file). It might however mess the table of contents in some cases (e.g. for Epub).
If you do not have a level-1 header in a markdown file:
- if it is a numbered chapter, Crowbook will infer a chapter name from the numbering scheme;
- if it is not numbered, chapter's title will default to the empty string and won't be displayed in the TOC.
Parts
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. So
@ Beginning
is equivalent to
@+ some_file.md
with some_file.md
containing only a title:
# Beginning
Crowbook options
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 to use 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 '!').
Here is the complete list of options, with a short description. The usage of some of them is detailed later on.
Metadata
author
- type: metadata
- default value:
""
- Author of the book
title
- type: metadata
- default value:
""
- Title of the book
lang
- type: metadata
- default value:
en
- Language of the book
subject
- type: metadata
- default value:
not set
- Subject of the book (used for EPUB metadata)
description
- type: metadata
- default value:
not set
- Description of the book (used for EPUB metadata)
cover
- type: path
- default value:
not set
- Path to the cover of the book
Additional metadata
license
- type: metadata
- default value:
not set
- License of the book
version
- type: metadata
- default value:
not set
- Version of the book
date
- type: metadata
- default value:
not set
- Date the book was revised
Output options
output.epub
- type: path
- default value:
not set
- Output file name for EPUB rendering
output.html
- type: path
- default value:
not set
- Output file name for HTML rendering
output.html_dir
- type: path
- default value:
not set
- Output directory name for HTML rendering
output.tex
- type: path
- default value:
not set
- Output file name for LaTeX rendering
output.pdf
- type: path
- default value:
not set
- Output file name for PDF rendering
output.odt
- type: path
- default value:
not set
- Output file name for ODT rendering
output.base_path
- type: path
- default value:
""
- Directory where those output files will we written
Rendering options
rendering.initials
- type: boolean
- default value:
false
- Use initials ('lettrines') for first letter of a chapter (experimental)
rendering.inline_toc
- type: boolean
- default value:
false
- Display a table of content in the document
rendering.inline_toc.name
- type: string
- default value:
"{{{loc_toc}}}"
- Name of the table of contents if it is displayed in document
rendering.num_depth
- type: integer
- default value:
1
- The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
rendering.chapter_template
- type: string
- default value:
"{{{number}}}\\. {{{chapter_title}}}"
- Naming scheme of chapters
Special option
import_config
- type: path
- default value:
not set
- Import another book configuration file
HTML options
html.icon
- type: path
- default value:
not set
- Path to an icon to be used for the HTML files(s)
html.header
- type: string
- default value:
not set
- Custom header to display at the beginning of html file(s)
html.footer
- type: string
- default value:
not set
- Custom footer to display at the end of HTML file(s)
html.css
- type: template path
- default value:
not set
- Path of a stylesheet for HTML rendering
html.css.add
- type: string
- default value:
not set
- Some inline CSS added to the stylesheet template
html.css.colours
- type: template path
- default value:
not set
- Path of a stylesheet for the colours for HTML
html.js
- type: template path
- default value:
not set
- Path of a javascript file
html.css.print
- type: template path
- default value:
not set
- Path of a media print stylesheet for HTML rendering
html.highlight_code
- type: boolean
- default value:
true
- Provides syntax highlighting for code blocks (using highlight.js)
html.highlight.js
- type: template path
- default value:
not set
- Set another highlight.js version than the bundled one
html.highlight.css
- type: template path
- default value:
not set
- Set another highlight.js CSS theme than the default one
html.side_notes
- type: boolean
- default value:
false
- Display footnotes as side notes in HTML/Epub (experimental)
html.escape_nb_spaces
- type: boolean
- default value:
true
- Replace unicode non breaking spaces with HTML entities and CSS
Standalone HTML options
html_single.one_chapter
- type: boolean
- default value:
false
- Display only one chapter at a time (with a button to display all)
html_single.html
- type: template path
- default value:
not set
- Path of an HTML template
html_single.js
- type: template path
- default value:
not set
- Path of a javascript file
Multifile HTML options
html_dir.index.html
- type: template path
- default value:
not set
- Path of index.html template
html_dir.chapter.html
- type: template path
- default value:
not set
- Path of a chapter.html template
EPUB options
epub.version
- type: integer
- default value:
2
- EPUB version to generate (2 or 3)
epub.css
- type: template path
- default value:
not set
- Path of a stylesheet for EPUB
epub.css.add
- type: string
- default value:
not set
- Inline CSS added to the EPUB stylesheet template
epub.chapter.xhtml
- type: template path
- default value:
not set
- Path of an xhtml template for each chapter
LaTeX options
tex.links_as_footnotes
- type: boolean
- default value:
true
- Add foontotes to URL of links so they are readable when printed
tex.command
- type: string
- default value:
xelatex
- LaTeX command to use for generating PDF
tex.template
- type: template path
- default value:
not set
- Path of a LaTeX template file
tex.template.add
- type: string
- default value:
not set
- Inline code added in the LaTeX template
tex.class
- type: string
- default value:
book
- LaTeX class to use
tex.paper_size
- type: string
- default value:
a5paper
- Specifies the size of the page.
tex.title
- type: boolean
- default value:
true
- If true, generate a title with maketitle
tex.font_size
- type: integer
- default value:
not set
- Specify latex font size (in pt, 10 (default), 11, or 12 are accepted)
Resources option
resources.files
- type: string
- default value:
not set
- Whitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
resources.out_path
- type: path
- default value:
data
- Paths where additional resources should be copied in the EPUB file or HTML directory
resources.base_path
- type: path
- default value:
not set
- Path where to find resources (in the source tree). By default, links and images are relative to the Markdown file. If this is set, it will be to this path.
resources.base_path.links
- type: path
- default value:
not set
- Set base path but only for links. Useless if resources.base_path is set
resources.base_path.images
- type: path
- default value:
.
- Set base path but only for images. Useless if resources.base_path is set
resources.base_path.files
- type: path
- default value:
.
- Set base path but only for additional files. Useless if resources.base_path is set.
resources.base_path.templates
- type: path
- default value:
.
- Set base path but only for templates files. Useless if resources.base_path is set
Input options
input.clean
- type: boolean
- default value:
true
- Toggle typographic cleaning of input markdown according to lang
input.clean.smart_quotes
- type: boolean
- default value:
true
- If enabled, tries to replace vertical quotations marks to curly ones
input.clean.ligature.dashes
- type: boolean
- default value:
false
- If enabled, replaces '--' to en dash ('–') and '---' to em dash ('—')
input.clean.ligature.guillemets
- type: boolean
- default value:
false
- If enabled, replaces '<<' and '>>' to french "guillemets" ('«' and '»')
input.yaml_blocks
- type: boolean
- default value:
false
- Enable inline YAML blocks to override options set in config file
Crowbook options
crowbook.temp_dir
- type: path
- default value: ``
- Path where to create a temporary directory (default: uses result from Rust's std::env::temp_dir())
crowbook.zip.command
- type: string
- default value:
zip
- Command to use to zip files (for EPUB/ODT)
crowbook.verbose
- type: boolean
- default value:
false
- Make Crowbook display more messages
Output options (for proofreading)
output.proofread.html
- type: path
- default value:
not set
- Output file name for HTML rendering with proofread features
output.proofread.html_dir
- type: path
- default value:
not set
- Output directory name for HTML rendering with proofread features
output.proofread.pdf
- type: path
- default value:
not set
- Output file name for PDF rendering with proofread features
Proofreading options (only for output.proofread.* targets)
proofread
- type: boolean
- default value:
false
- If set to false, will disactivate proofreading even if one of output.proofread.x is present
proofread.nb_spaces
- type: boolean
- default value:
true
- Highlight non breaking spaces so it is easier to see if typography is correct
proofread.languagetool
- type: boolean
- default value:
false
- If true, try to use language tool server to grammar check the book
proofread.languagetool.port
- type: integer
- default value:
8081
- Port to connect to languagetool-server
proofread.repetitions
- type: boolean
- default value:
false
- If set to true, use Caribon to detect repetitions
proofread.repetitions.max_distance
- type: integer
- default value:
25
- Max distance between two occurences so it is considered a repetition
proofread.repetitions.fuzzy
- type: boolean
- default value:
true
- Enable fuzzy string matching
proofread.repetitions.fuzzy.threshold
- type: float
- default value:
0.2
- Max threshold of differences to consider two strings a repetition
proofread.repetitions.ignore_proper
- type: boolean
- default value:
true
- Ignore proper nouns for repetitions
proofread.repetitions.threshold
- type: float
- default value:
2.0
- Threshold to detect a repetition
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). 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.
Metadata
Metadata are data about the book. Except for cover
, which points to
an image file, all its fields are strings. The main metadata are:
author
: the author(s) of the book.title
: the title of the book.lang
: the language of the book. The unicode language code should be used, e.g.en_GB
oren
,fr_FR
, ...cover
: path to an image file for the cover of the book (not displayed in all output formats).
There are also additional metadata:
subject
description
license
version
date
You can define your own metadata by starting an option name with
metadata.foo
.
All metadata are accessible from templates, see Templates.
The import_config
special option
The special import_config
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_config: common.book
title: Foo
+ foo_01.md
+ foo_02.md
Or include it in bar.book
, but override some of its features:
import_config: common.book
title: Bar
license: CC-BY-SA # Override the license from common.book
+ bar_01.md
Output options
These options specify which files to generate.
Recall that all file paths are relative to the directory where the
config file is, not to the one where you run crowbook
. So if you set
output.epub: foo.epub
and runs
$ 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
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 the 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:
output.html
: renders a standalone HTML file.output.html_dir
: render a HTML directory with one page by chapter.output.epub
: renders an EPUB file.output.tex
: renders a LaTeX file.output.pdf
: renders a PDF file (usingtex.command
).
(There are other output options for generating proofreading files, see Proofreading.)
output.base_path
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
.
Input options
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:
input.clean
: if set tofalse
, will disable all typographic "cleaning" (default:true
). Theclean
algorithm is dependent on the language, though currently there is only a variant implemented forfr
(french), dealing with the specific non-breaking spaces rules for this language.input.clean.smart_quotes
: if set tofalse
, disable the "smart quote" feature, that (tries to) replace straight quotes with curly ones. As it is an heuristics and can't be perfect, you might want to disable it in some circumstances (default:true
).input.clean.ligature_dashes
: if set totrue
, will convert--
to en dash (–
) and---
to em dash (—
). This can be useful if you want to use these characters but can't access them easily on your keymap; however, as it can also cause problems if you do want to have two successive dashes, it is disabled by default.input.clean.ligature_guillemets
is a similar feature for french 'guilemets', replacing<<
and>>
to«
and»
. For the same reason, it is also disabled by default.
Generic options for rendering
These options allow to configure the rendering; they are used (or at least should be) for all formats.
rendering.num_depth
An integer that represents the maximum level of numbering for your
book. E.g., 1
will only number chapters, while 2
will number
chapters, sections, but not anything below that. 6
is the maximum level
and turns numbering on for all headers.
default: 1
rendering.chapter_template
A string that will be used for chapter titles. You can use {{{number}}}
and
{{{title}}}
in this string, e.g.:
numbering_template: "Chapter {{{number}} {{title}}}"
Note that:
- in this case, quoting is necessary because
{
and}
have special meaning in YAML; - this string won't be used for unnumbered chapters;
- this string isn't currently used by LaTeX, either.
It is possible to include Markdown formatting in this template, but it isn't advised, because it might cause problems for some formats (e.g. your EPUB file might not be correct anymore).
Other rendering options
rendering.inline_toc
: if set to true, Crowbook will include a table of contents at the beginning of the document.rendering.inline_toc.name
: the name of this table of contents as it should be displayed in the document.rendering.initials
: if set to true, Crowbook will use initials, or "lettrines", displaying the first letter of each chapter bigger than the others.
Resources options
These options allow to embed additional files for some formats (currently, only EPUB). This can be useful for embedding fonts.
resources.files
A list of files or directories that should be added. It's a whitespace-separated list, so it can be, e.g.:
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
resources.out_path
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