Crowbook User Guide 0.15.0
+Crowbook User Guide 0.15.0
Table of contents
+-
+
- 1. Crowbook + + +
- 2. Arguments + + +
- 3. The configuration file
+
- 3.1. Configuration in an inline YAML block +
- 3.2. The list of files + + +
- 3.3. Crowbook options + + +
- 3.4. Full list of options
+
- 3.4.1. Metadata + + +
- 3.4.2. Additional metadata + + +
- 3.4.3. Output options + + +
- 3.4.4. Rendering options
+
- 3.4.4.1.
rendering.highlight
+ - 3.4.4.2.
rendering.highlight.theme
+ - 3.4.4.3.
rendering.initials
+ - 3.4.4.4.
rendering.inline_toc
+ - 3.4.4.5.
rendering.inline_toc.name
+ - 3.4.4.6.
rendering.num_depth
+ - 3.4.4.7.
rendering.chapter
+ - 3.4.4.8.
rendering.part
+ - 3.4.4.9.
rendering.chapter.roman_numerals
+ - 3.4.4.10.
rendering.part.roman_numerals
+ - 3.4.4.11.
rendering.part.reset_counter
+ - 3.4.4.12.
rendering.chapter.template
+ - 3.4.4.13.
rendering.part.template
+
+
+ - 3.4.4.1.
- 3.4.5. Special option
+
- 3.4.5.1.
import
+
+
+ - 3.4.5.1.
- 3.4.6. HTML options
+
- 3.4.6.1.
html.icon
+ - 3.4.6.2.
html.highlight.theme
+ - 3.4.6.3.
html.header
+ - 3.4.6.4.
html.footer
+ - 3.4.6.5.
html.css
+ - 3.4.6.6.
html.css.add
+ - 3.4.6.7.
html.css.colors
+ - 3.4.6.8.
html.js
+ - 3.4.6.9.
html.css.print
+ - 3.4.6.10.
html.highlight.js
+ - 3.4.6.11.
html.highlight.css
+ - 3.4.6.12.
html.side_notes
+ - 3.4.6.13.
html.escape_nb_spaces
+ - 3.4.6.14.
html.chapter.template
+ - 3.4.6.15.
html.part.template
+
+
+ - 3.4.6.1.
- 3.4.7. Standalone HTML options + + +
- 3.4.8. Multifile HTML options + + +
- 3.4.9. Interactive fiction HTML options + + +
- 3.4.10. EPUB options + + +
- 3.4.11. LaTeX options
+
- 3.4.11.1.
tex.highlight.theme
+ - 3.4.11.2.
tex.links_as_footnotes
+ - 3.4.11.3.
tex.command
+ - 3.4.11.4.
tex.template
+ - 3.4.11.5.
tex.template.add
+ - 3.4.11.6.
tex.class
+ - 3.4.11.7.
tex.paper.size
+ - 3.4.11.8.
tex.margin.left
+ - 3.4.11.9.
tex.margin.right
+ - 3.4.11.10.
tex.margin.top
+ - 3.4.11.11.
tex.margin.bottom
+ - 3.4.11.12.
tex.title
+ - 3.4.11.13.
tex.font.size
+ - 3.4.11.14.
tex.hyperref
+ - 3.4.11.15.
tex.stdpage
+
+
+ - 3.4.11.1.
- 3.4.12. Resources option + + +
- 3.4.13. Input options + + +
- 3.4.14. Crowbook options + + +
- 3.4.15. Output options (for proofreading) + + +
- 3.4.16. Proofreading options (only for
output.proofread.*
targets) +- 3.4.16.1.
proofread
+ - 3.4.16.2.
proofread.languagetool
+ - 3.4.16.3.
proofread.languagetool.port
+ - 3.4.16.4.
proofread.grammalecte
+ - 3.4.16.5.
proofread.grammalecte.port
+ - 3.4.16.6.
proofread.repetitions
+ - 3.4.16.7.
proofread.repetitions.max_distance
+ - 3.4.16.8.
proofread.repetitions.fuzzy
+ - 3.4.16.9.
proofread.repetitions.fuzzy.threshold
+ - 3.4.16.10.
proofread.repetitions.ignore_proper
+ - 3.4.16.11.
proofread.repetitions.threshold
+
+
+
+ - 3.4.16.1.
+
+
+ - 4. Markdown format + + +
- 5. Templates
+
- 5.1. Create and edit template + + +
- 5.2. List of templates
+
- 5.2.1. html.js +
- 5.2.2. html.css +
- 5.2.3. html.css.colors +
- 5.2.4. html.css.print +
- 5.2.5. html.highlight.js +
- 5.2.6. html.highlight.css +
- 5.2.7. html.standalone.js +
- 5.2.8. html.standalone.template +
- 5.2.9. html.dir.template +
- 5.2.10. tex.template +
- 5.2.11. epub.chapter.xhtml +
- 5.2.12. epub.css +
- 5.2.13. Inline templates + +
+ - 5.3. List of accessible variables + + + +
+ - 6. Proofreading with Crowbook + + +
- 7. Interactive fiction + + +
- 8. Tips and tricks + + +
- 9. Contributing + + +
- ChangeLog
+
- 0.15.1 (2020-07-07) +
- 0.15.0 (2019-07-18) +
- 0.14.1 (2018-06-01) +
- 0.14.0 (2017-11-26) +
- 0.14.0-beta (2017-10-08) +
- 0.13.0 (2017-07-14) +
- 0.12.0 (2017-06-05) +
- 0.11.4 (2017-03-21) +
- 0.11.3 (2017-03-19) +
- 0.11.2 (2017-03-05) +
- 0.11.1 (2017-01-05) +
- 0.11.0 (2016-12-31) +
- 0.10.4 (2016-12-16) +
- 0.10.3 (2016-11-19) +
- 0.10.2 (2016-10-21) +
- 0.10.1 (2016-10-18) +
- 0.10.0 (2016-10-18) +
- 0.9.1 (2016-09-29) +
- 0.9.0 (2016-09-23) +
- 0.8.0 (2016-09-19) +
- 0.7.0 (2016-09-11) +
- 0.6.0 (2016-09-09) +
- 0.5.1 (2016-04-14) +
- 0.5.0 (2016-04-02) +
- 0.4.0 (2016-03-01) +
- 0.3.0 (2016-02-27) +
- 0.2.2 (2016-02-25) +
- 0.2.1 (2016-02-25) +
- 0.2.0 (2016-02-25) +
- 0.1.0 (2016-02-21) + +
+ - GNU LESSER GENERAL PUBLIC LICENSE + +
Chapter 1
Crowbook
Crowbook’s aim is to allow you to write a book in Markdown without worrying about formatting or typography, and let the program generate HTML, PDF and EPUB output for you. Its focus is novels and fiction, and the default settings should (hopefully) generate readable books with correct typography without requiring you to worry about it.
1.1. Example
@@ -731,10 +1406,10 @@ function toggle() {You can also play with the online demo version.
1.2. Installing
There are two ways to install Crowbook: either using precompiled binaries, or compiling it using cargo
.
Binaries
+1.2.1. Binaries
See the releases page to download a precompiled binary for your architecture (currently: Linux, Windows and MacOSX). Just extract the archive and run crowbook
(or crowbook.exe
on Windows). You might also want to copy the binary somewhere in your PATH
for later usage.
If you are on Debian GNU/Linux or Ubuntu (on a PC architecture), you can also download .deb
packages on the releases page.
Using Cargo
+1.2.2. Using Cargo
Cargo is the package manager for Rust. You can install it here. Once that is done:
$ cargo install crowbook
will automatically download the latest crowbook
release on crates.io, compile it, and install it on your system.
This will generate a default my.book
file, which you’ll need to complete. This configuration file contains some metadata, options, and lists the Markdown files.
For short books containing only a single Markdown file, it is possible to embed some metadata at the beginning of the file and use the --single
or -s
option to run crowbook
directly on this Markdown file and avoid creating a separate book configuration file:
$ crowbook -s text.md -
For more information, see the chapters on the arguments supported by crowbook
and on the configuration file.
For more information, see the chapters on the arguments supported by crowbook
and on the configuration file.
1.5. Current features
-Output formats
+1.5.1. Output formats
Crowbook supports HTML, PDF and EPUB (either version 2 or 3) as output formats. See the Crowbook User Guide rendered in HTML, EPUB and PDF.
-Input format
+1.5.2. Input format
Crowbook uses pulldown-cmark and thus should support most of CommonMark Markdown. Inline HTML, however, is not implemented, and probably won’t be, as the goal is to have books that can also be generated in PDF (and maybe ODT).
-Typographic “cleaning”
+1.5.3. Typographic “cleaning”
Maybe the most specific “feature” of Crowbook is that it does its best to “clean” the input text before rendering it. By default, it removes superfluous spaces and tries to use curly quotes. If the book’s language is set to french, it also tries to respect french typography by replacing spaces with non-breaking ones when it is appropriate (e.g. before ‘?’, ‘!’, ‘;’ or ‘:’).
-Please open an issue describing typographic rules if you want them to be implemented for other languages.
Links handling
+1.5.4. Links handling
Crowbook tries to correctly translate local links in the input Markdown files: e.g. if you have a link to a Markdown file that is part of your book, it will be transformed into a link inside the document.
-Inline YAML blocks
+1.5.5. Inline YAML blocks
Crowbook supports inline YAML blocks:
--- author: Me title: My title ---
This is mostly useful when Crowbook is run with the --single
argument (receiving a single Markdown file instead of a book configuration file), for short texts that only contain one “chapter”.
Proofreading
-Crowbook can also generate “proofreading” copies in HTML or PDF, highlighting grammar errors and repetitions. For more information, see the proofreading chapter of the guide.
-Interactive fiction
-Crowbook has experimental support for writing interactive fiction (only for HTML). For more information, read the interactive fiction chapter.
-Customization
-While the default settings will hopefully generate something that should look “good enough”, it is possible to customize the output, essentially by providing different templates.
-Bugs
+1.5.6. Proofreading
+Crowbook can also generate “proofreading” copies in HTML or PDF, highlighting grammar errors and repetitions. For more information, see the proofreading chapter of the guide.
+1.5.7. Interactive fiction
+Crowbook has experimental support for writing interactive fiction (only for HTML). For more information, read the interactive fiction chapter.
+1.5.8. Customization
+While the default settings will hopefully generate something that should look “good enough”, it is possible to customize the output, essentially by providing different templates.
+1.5.9. Bugs
See the issue tracker on GitHub.
1.6. Contributors
-
@@ -800,7 +1475,7 @@ title: M
1.8. ChangeLog
See ChangeLog.
1.9. Contributing
-See how you can contribute to Crowbook.
+See how you can contribute to Crowbook.
If you find this project useful, you can also support its author by making a Paypal donation.
1.10. Library
While the main purpose of Crowbook is to be run as a standalone program, the code is written as a library, so if you want to build on it you can use it as such. You can look at the generated documentation on docs.rs.
@@ -821,12 +1496,14 @@ title: MChapter 2
Arguments
Crowbook can take a number of arguments, generally in the form:
crowbook [OPTIONS] [BOOK] -
The most important argument is obviously the book configuration file. It is mandatory in most cases: if you don’t pass it, Crowbook will simply display an error. In a normal use case this is the only argument you’ll need to pass, as most options will be set in this configuration file.
+The most important argument is obviously the book configuration file. It is mandatory in most cases: if you don’t pass it, crowbook
will simply display an error. In a normal use case this is the only argument you’ll need to pass, as most options will be set in this configuration file.
It is, however, possible to pass more arguments to crowbook
:
2.1. --create
-Usage: crowbook [BOOK] --create file_1.md file_2.md ...
(or crowbook [BOOK] -c file_1.md file_2.md ...
)
Creates a new book from a list of Markdown files. It will generate a book configuration file with all file names specified as chapters. It either prints the result to stdout (if BOOK
is not specified) or generate the file BOOK
(or abort if it already exists).
Usage:
+crowbook [BOOK] --create file_1.md file_2.md ... +
or:
+crowbook [BOOK] -c file_1.md file_2.md ... +
Creates a new book from a list of Markdown files. It will generate a book configuration file with all file names specified as chapters. It either prints the result to stdout
(if BOOK
is not specified) or generates the file BOOK
(or abort if it already exists).
crowbook foo.book --create chapter_1.md chapter_2.md chapter_3.md
will thus generate a file foo.book
containing:
author: Your name @@ -852,11 +1529,14 @@ lang: en + chapter_3.md
while
crowbook --create chapter_1.md chapter_2.md chapter_3.md -
will print the same result, but to stdout (without creating a file).
+will print the same result, but to stdout
(without creating a file).
2.2. --single
-Usage: crowbook --single <FILE>
(or crowbook -s <FILE>
)
This argument allows you to give crowbook
a single Markdown file. This file can contain an inline YAML block to set some book options. Inline YAML blocks must start and end with a line containing only ---
(three dashes). E.g:
Usage:
+crowbook --single <FILE> +
or:
+crowbook -s <FILE> +
This argument allows you to give crowbook
a single Markdown file. This file can contain an inline YAML block to set some book options. Inline YAML blocks must start and end with a line containing only ---
(three dashes).
E.g:
--- author: Joan Doe title: A short story @@ -864,41 +1544,52 @@ output: [Content of the story in Markdown. -
If this YAML block is not at the beginning of a file, it must also be preceded by a blank line.
-This allows to not have to write a .book
configuration file for a short story or an article. crowbook -s foo.md
is rougly equivalent to having a book configuration file containing:
If this YAML block is not at the beginning of a file, it must also be preceded by a blank line.
+This allows to not have to write a .book
configuration file for a short story or an article. crowbook -s foo.md
is rougly equivalent to having a book configuration file containing:
! foo.md -
That is, the chapter heading (if any) won’t be displayed in the output documents (though they still appear in the TOC).
-Note that by default, using
+--single
or-s
sets the default LaTeX class of the book toarticle
instead ofbook
.That is, the chapter heading (if any) won’t be displayed in the output documents (though they still appear in the TOC).
+Note that by default, using
--single
or-s
sets the default LaTeX class of the book toarticle
instead ofbook
.2.3.
---set
Usage:
-crowbook <BOOK> --set [KEY] [VALUE]...
This argument takes a list of
+KEY
VALUE
pairs and allows setting or overriding a book configuration option. All valid options in the configuration files are valid as keys. For more information, see the configuration file.Usage:
+crowbook <BOOK> --set [KEY] [VALUE]... +This argument takes a list of
KEY
VALUE
pairs and allows setting or overriding a book configuration option. All valid options in the configuration files are valid as keys. For more information, see the configuration file.$ crowbook foo.book --set tex.paper.size a4paper -will override the paper size for PDF generation.
+will override the paper size for PDF generation.
2.4.
---list-options
Usage:
-crowbook --list-options
(or
-crowbook -l
)Displays all the valid options that can be used, whether in a book configuration file, with
+--set
, or in an inline YAML block.Usage:
+crowbook --list-options +or:
+crowbook -l +Displays all the valid options that can be used, whether in a book configuration file, with
--set
, or in an inline YAML block.2.5.
---print-template
Usage:
-crowbook --print-template <TEMPLATE>
Prints the built-in template to stdout. Useful if you want to customize the appearance of your document. E.g., if you want to modify the CSS used for HTML rendering:
+Usage:
+crowbook --print-template <TEMPLATE> +Prints the built-in template to
+stdout
. Useful if you want to customize the appearance of your document.E.g., if you want to modify the CSS used for HTML rendering:
$ crowbook --print-template html.css > my_style.css # edit my_style.css in your favourite editor $ crowbook my.book --set html.css my_style.css # or add "html.css: my_style.css" in my.book2.6.
---stats
Usage:
-crowbook --stats <BOOK>
(or
-crowbook -S <BOOK>
)Display some statistics (word and character counts) about the book.
+Usage:
+crowbook --stats <BOOK> +or:
+crowbook -S <BOOK> +Display some statistics (word and character counts) about the book.
2.7.
---proofread
Usage:
-crowbook --proofread <BOOK>
(or
-crowbook -p <BOOK>
)Equivalent to
+--set proofread true
, enables proofreading. See Proofreading.Usage:
+crowbook --proofread <BOOK> +or:
+crowbook -p <BOOK> +Equivalent to
--set proofread true
, enables proofreading. See Proofreading.2.8.
---autograph
Usage:
-crowbook --autograph <BOOK>
(or
-crowbook -a <BOOK>
)Prompts for a an autograph execution. This is a Markdown block that will be inserted at the beginning of the book.
-Example
+Usage:
+crowbook --autograph <BOOK> +or:
+crowbook -a <BOOK> +Prompts for a an autograph execution. This is a Markdown block that will be inserted at the beginning of the book.
+2.8.1. Example
$ crowbook --autograph my.book CROWBOOK 0.14.0 Enter autograph: @@ -906,37 +1597,44 @@ To my dear friend John, Cheers, *Joan* ^D -
will add the block of text that was entered to all output files.
+will add the block of text that was entered to all output files.
2.9.
---verbose
Usage:
-crowbook <BOOK> --verbose
If this flag is set, Crowbook will print more warnings it detects while parsing and rendering.
+Usage:
+crowbook <BOOK> --verbose +If this flag is set, Crowbook will print more warnings it detects while parsing and rendering.
2.10.
---to
Usage:
-crowbook <BOOK> --to [FORMAT]
(or
-crowbook <BOOK> -t [FORMAT]
)Generate only the specified format.
-FORMAT
must be eitherepub
,html
,html.dir
,odt
ortex
.If an output file for the format is not specified in the book configuration file,
-crowbook
will fail to render PDF, ODT and EPUB, whereas it will print HTML and TeX files on stdout. It is, however, possible to specify a file with the--output
option.Examples
+Usage:
+crowbook <BOOK> --to [FORMAT] +or:
+crowbook <BOOK> -t [FORMAT] +Generate only the specified format.
+FORMAT
must be eitherepub
,html
,html.dir
,odt
ortex
.If an output file for the format is not specified in the book configuration file,
+crowbook
will fail to render PDF, ODT and EPUB, whereas it will print HTML and TeX files on stdout. It is, however, possible to specify a file with the--output
option.2.10.1. Examples
crowbook --to html foo.book -will generate some HTML, and prints it either to the file specified by
+output.html
infoo.book
, or to stdout if it is not specified.will generate some HTML, and prints it either to the file specified by
output.html
infoo.book
, or to stdout if it is not specified.crowbook --to pdf --output foo.pdf foo.book -will generate a
+foo.pdf
file.will generate a
foo.pdf
file.2.11.
---output
Usage:
-crowbook <BOOK> --to <FORMAT> --output <FILE>
(or
-crowbook -t <FORMAT> -o <FILE> <BOOK>
)Specifies an output file. Only valid when
+--to
is used.Usage:
+crowbook <BOOK> --to <FORMAT> --output <FILE> +or:
+crowbook -t <FORMAT> -o <FILE> <BOOK> +Specifies an output file. Only valid when
--to
is used.2.12.
---lang
Usage:
-crowbook --lang <LANG>
(or
-crowbook -L <LANG>
)Set the runtime language used by Crowbook. Currently, only a french translation is available. By default, Crowbook uses the
-LANG
environment variable to determine which language to use, but this option allows to override it (e.g. for operating systems that don’t use such an option, such as Windows).Example
--
$ crowbook --lang fr --help
will display Crowbook’s help message in french.
-Note that this argument has nothing to do with the
+lang
option that you can set in the book configuration file, which specifies the language of the book. This argument specifies the language of the text messages that Crowbook will display while running, but has no effect on the generated documents.Usage:
+crowbook --lang <LANG> +or:
+crowbook -L <LANG> +Set the runtime language used by Crowbook. Currently, only a french translation is available. By default, Crowbook uses the
+LANG
environment variable to determine which language to use, but this option allows to override it (e.g. for operating systems that don’t use such an option, such as Windows).2.12.1. Example
+$ crowbook --lang fr --help +will display Crowbook’s help message in french.
+Note that this argument has nothing to do with the
lang
option that you can set in the book configuration file, which specifies the language of the book. This argument specifies the language of the text messages that Crowbook will display while running, but has no effect on the generated documents.
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:
+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 @@ -951,16 +1649,16 @@ output: [- epilogue.md -
Basically, it is divided in two parts:
+Basically, it is divided in two parts:
-
-
a list of options, under the form
+key: value
, following YAML syntax.a list of options, under the form
key: value
, following YAML syntax.
-a list of Markdown files.
+a list of Markdown files.
Lines starting with the #
characters are comments and are discarded.
Lines starting with the #
characters are comments and are discarded.
3.1. Configuration in an inline YAML block
-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 ---
:
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 @@ -972,27 +1670,27 @@ 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
+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 withcrowbook --single
(orcrowbook -s
).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
).3.2. The list of files
-There are various options to include a Markdown file.
+There are various options to include a Markdown file.
-
-+
+ file_name.md
includes a numbered chapter.- -
+ file_name.md
includes a numbered chapter.+
- file_name.md
includes an unnumbered 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.- -
! 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.- -
42. file_name.md
specifies the number for a chapter.+
@
includes a part instead of a chapter.
@
includes a part instead of a chapter.So a typical usage might look like this:
+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 @@ -1000,21 +1698,21 @@ output: [html, pdf, epub] + chapter_1.md + chapter_2.md ... -There are two important things to note:
+There are two important things to note:
-
-you must not use quotes around the file names.
+- -
you must not use quotes around the file names.
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.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:
+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.: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
-Parts are included using the
+@
character, followed by the same characters than for chapters: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).
+3.2.1. Parts
+Parts are included using the
@
character, followed by the same characters than for chapters:@+ numbered_part.md + chapter_01.md + chapter_02.md @@ -1023,7 +1721,7 @@ output: [html, pdf, epub] + 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: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 @@ -1032,267 +1730,266 @@ output: [html, pdf, epub] + chapter_04.md @ Appendix - notes.md -
With this shortcut, parts are always numbered.
-Subchapters
-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:
+With this shortcut, parts are always numbered.
+3.2.2. Subchapters
+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.
+-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 insubsection.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.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 insubsection.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.3.3. 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.: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:
+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: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
-Metadata are data about the book. Except for
+cover
, which points to an image file, all its fields are strings. The main metadata are: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.
(wherex
is a number) or!
).3.3.1. 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
- -
author
+
title
- -
title
+
subtitle
- -
subtitle
+
lang
, the language of the book. The unicode language code should be used, e.g.en_GB
oren
,fr_FR
, orfr
...- -
lang
, the language of the book. The unicode language code should be used, e.g.en_GB
oren
,fr_FR
, orfr
...+
cover
, a path to an image file for the cover of the book (not displayed in all output formats).
cover
, a path to an image file for the cover of the book (not displayed in all output formats).There are also additional metadata:
+There are also additional metadata:
-
-+
subject
- -
subject
+
description
- -
description
+
license
- -
license
+
version
- -
version
+
date
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
special optionThe 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 bothfoo.book
andbar.book
, you can create acommon.book
file:You can define your own metadata by starting an option name with
+metadata.foo
.All metadata are accessible from templates, see Templates.
+3.3.2. The
+import
special optionThe 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 bothfoo.book
andbar.book
, you can create acommon.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
: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: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 -Output options
-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:3.3.3. Output options
+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
+and run
$ crowbook some/dir/config.book --
foo.epub
will be generated insome/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+
foo.epub
will be generated insome/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 withtex.command
) to generate a PDF file, so PDF rendering won’t work if it is not installed on your system. Crowbook also uses thezip
command to generate the EPUB and ODT files.Current output options are:
+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 withtex.command
) to generate a PDF file, so PDF rendering won’t work if it is not installed on your system. Crowbook also uses thezip
command to generate the EPUB and ODT files.Current output options are:
-
-+
output.html
: renders a standalone HTML file.- -
output.html
: renders a standalone HTML file.+
output.html.dir
: renders a HTML directory with one page by chapter.- -
output.html.dir
: renders a HTML directory with one page by chapter.+
output.epub
: renders an EPUB file.- -
output.epub
: renders an EPUB file.+
output.tex
: renders a LaTeX file.- -
output.tex
: renders a LaTeX file.+
output.pdf
: renders a PDF file (usingtex.command
).
output.pdf
: renders a PDF file (usingtex.command
).(There are other output options for generating proofreading files, see Proofreading, and interactive fiction, see Interactive fiction.)
-The
-output
optionSetting 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:(There are other output options for generating proofreading files, see Proofreading, and interactive fiction, see Interactive fiction.)
+3.3.3.1. The
+output
optionSetting 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:
+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
(ormy_book.md
), it will generatemy_book.pdf
,my_book.html
andmy_book.epub
.You can also infer the output file name by specifying “auto” to e.g.
+output.html
. The previous example is thus equivalent toThis 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
(ormy_book.md
), it will generatemy_book.pdf
,my_book.html
andmy_book.epub
.-You can also infer the output file name by specifying “auto” to e.g.
output.html
. The previous example is thus equivalent tooutput.pdf: auto output.epub: auto output.html: auto-
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.,3.3.3.2.
+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:
+will render the EPUB file in
+docs/book/book.epub
.3.3.4. 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
(default:true
): if set tofalse
, will disable all typographic “cleaning”. The 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
(default:true
): if set tofalse
, will disable all typographic “cleaning”. The 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
(default:true
): 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.- -
input.clean.smart_quotes
(default:true
): 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.+
input.clean.ligature_dashes
(default:false
): 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_dashes
(default:false
): 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
(default:false
): is a similar feature for french ‘guillemets’, replacing<<
and>>
to«
and»
.
input.clean.ligature_guillemets
(default:false
): is a similar feature for french ‘guillemets’, replacing<<
and>>
to«
and»
.Generic options for rendering
-These options allow to configure the rendering; they are used (or at least should be) for all formats.
+3.3.5. Generic options for rendering
+These options allow to configure the rendering; they are used (or at least should be) for all formats.
-
-+
rendering.highlight
(default:syntect
): specify if and how to perform syntax highlighting for code blocks. Valid values are:
rendering.highlight
(default:syntect
): specify if and how to perform syntax highlighting for code blocks. Valid values are:-
+
syntect
: uses the syntect library to perform syntax highlighting. This has the advantage of also enabling syntax highlighting for LaTeX/PDF and EPUB formats; however syntect support doesn’t seem to work on Windows.- -
syntect
: uses the syntect library to perform syntax highlighting. This has the advantage of also enabling syntax highlighting for LaTeX/PDF and EPUB formats; however syntect support doesn’t seem to work on Windows.+
highlight.js
: this will use (and embed)highlight.js
for HTML rendering, and will not perform any syntax highlighting for other output formats.- -
highlight.js
: this will use (and embed)highlight.js
for HTML rendering, and will not perform any syntax highlighting for other output formats.+
none
: disable syntax highlighting.
none
: disable syntax highlighting.If your version of Crowbook (as is the case for Windows builds) isn’t built with
+syntect
support, it will default tonone
if you try to use it.If your version of
crowbook
(as is the case for Windows builds) isn’t built withsyntect
support, it will default tonone
if you try to use it.-
-+
rendering.highlight.theme
: only used ifrendering.highlight
is set tosyntect
, selects the theme to use for syntax highlighting. Default is “InspiredGitHub”. Valid theme names are:- -
rendering.highlight.theme
: only used ifrendering.highlight
is set tosyntect
, selects the theme to use for syntax highlighting. Default is “InspiredGitHub”. Valid theme names are:-
“InspiredGitHub”
+- -
“InspiredGitHub”
“Solarized (dark)”
+- -
“Solarized (dark)”
“Solarized (light)”
+- -
“Solarized (light)”
“base16-eighties.dark”
+- -
“base16-eighties.dark”
“base16-mocha.dark”
+- -
“base16-mocha.dark”
“base16-ocean.dark”
+- -
“base16-ocean.dark”
and “base16-ocean.light”.
+and “base16-ocean.light”.
+
rendering.num_depth
: an integer that represents the maximum level of numbering for your book. E.g.,1
will only number chapters, while2
will number chapters, sections, but not anything below that.6
is the maximum level and turns numbering on for all headers. (Default is1
.) This also affects what levels will be displayed in the table of contents.- -
rendering.num_depth
: an integer that represents the maximum level of numbering for your book. E.g.,1
will only number chapters, while2
will number chapters, sections, but not anything below that.6
is the maximum level and turns numbering on for all headers. (Default is1
.) This also affects what levels will be displayed in the table of contents.+
rendering.chapter
andrendering.part
: the strings that will be used to design chapter and part. E.g., if you want your parts to show as “Book III” instead of “Part III”, you can setrendering.part: Book
.- -
rendering.chapter
andrendering.part
: the strings that will be used to design chapter and part. E.g., if you want your parts to show as “Book III” instead of “Part III”, you can setrendering.part: Book
.+
rendering.part.roman_numerals
andrendering.chapter.roman_numerals
: these two booleans allow you to specify if you want roman numerals for part or chapter numbers (default istrue
for part numbers, andfalse
for chapter numbers).- -
rendering.part.roman_numerals
andrendering.chapter.roman_numerals
: these two booleans allow you to specify if you want roman numerals for part or chapter numbers (default istrue
for part numbers, andfalse
for chapter numbers).+
rendering.inline_toc
: if set to true, Crowbook will include a table of contents at the beginning of the document.- -
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.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.- -
rendering.initials
: if set to true, Crowbook will use initials, or “lettrines”, displaying the first letter of each chapter bigger than the others.+
rendering.part.reset_counter
: set it tofalse
if you don’t want your chapter numbers to start again at 1 at each part.
rendering.part.reset_counter
: set it tofalse
if you don’t want your chapter numbers to start again at 1 at each part.HTML Options
-These options allow you to customize the HTML rendering (used both by the default HTML standalone renderer and the HTML multifile renderer):
+3.3.6. HTML Options
+These options allow you to customize the HTML rendering (used both by the default HTML standalone renderer and the HTML multifile renderer):
-
-+
html.icon
: allows to set afavicon
for the page.- -
html.icon
: allows to set afavicon
for the page.+
html.header
andhtml.footer
: allow to set a custom (Markdown) string at the top and at the bottom of the HTML page. This is actually a template, so you can access metadata, such as{{{author}}}
,{{{title}}}
, or{{{version}}}
in it. See the template chapter for more information on the fields you can use.- -
html.header
andhtml.footer
: allow to set a custom (Markdown) string at the top and at the bottom of the HTML page. This is actually a template, so you can access metadata, such as{{{author}}}
,{{{title}}}
, or{{{version}}}
in it. See the template chapter for more information on the fields you can use.+
html.css
: allows to set up a custom CSS file. You can also redefine the colors in a file and set it usinghtml.css.colors
.- -
html.css
: allows to set up a custom CSS file. You can also redefine the colors in a file and set it usinghtml.css.colors
.+
html.css.add
: allows you to add some specific lines of CSS in your book configuration file, that will be appended after the default CSS template.- -
html.css.add
: allows you to add some specific lines of CSS in your book configuration file, that will be appended after the default CSS template.+
html.highlight.theme
: is similar torendering.highlight.theme
but only sets the theme for HTML output.
html.highlight.theme
: is similar torendering.highlight.theme
but only sets the theme for HTML output.Options for standalone HTML
-There are a few options specific to the standalone HTML renderer (default, set with
+output.html
):3.3.6.1. Options for standalone HTML
+There are a few options specific to the standalone HTML renderer (default, set with
output.html
):-
-+
html.standalone.one_chapter
: if set to true, will only display one chapter at a time (using Javascript), making it look similarly to the multifile HTML.- -
html.standalone.one_chapter
: if set to true, will only display one chapter at a time (using Javascript), making it look similarly to the multifile HTML.+
html.standalone.template
: allows you to change or modify the HTML template for standalone HTML.
html.standalone.template
: allows you to change or modify the HTML template for standalone HTML.Options for LaTeX/PDF rendering
-These options allow you to customize the LaTeX renderer (and, thus, the generated PDF documents):
+3.3.7. Options for LaTeX/PDF rendering
+These options allow you to customize the LaTeX renderer (and, thus, the generated PDF documents):
-
-+
tex.template
: specifies a different LaTeX template.- -
tex.template
: specifies a different LaTeX template.+
tex.class
: changes the LaTeX class used.- -
tex.class
: changes the LaTeX class used.+
tex.paper.size
andtex.font.size
: (defaulta5paper
and10pt
) allows to modify the page and font size.- -
tex.paper.size
andtex.font.size
: (defaulta5paper
and10pt
) allows to modify the page and font size.+
tex.margin.left
,tex.margin.right
,tex.margin.top
andtex.margin.bottom
: specify the margin of the page.- -
tex.margin.left
,tex.margin.right
,tex.margin.top
andtex.margin.bottom
: specify the margin of the page.+
tex.links_as_footnotes
: can be set tofalse
if you don’t want links to also appear as footnotes (which means losing them if it is actually printed).- -
tex.links_as_footnotes
: can be set tofalse
if you don’t want links to also appear as footnotes (which means losing them if it is actually printed).+
tex.highlight.theme
: similar torendering.highlight.theme
, but only sets the theme for LaTeX/PDF rendering.
tex.highlight.theme
: similar torendering.highlight.theme
, but only sets the theme for LaTeX/PDF rendering.Options for EPUB rendering
-There are also options specific to the EPUB format:
+3.3.8. Options for EPUB rendering
+There are also options specific to the EPUB format:
-
-+
epub.version
: can be set to 2 or 3 (default 2).- -
epub.version
: can be set to 2 or 3 (default 2).+
epub.css
: can be useful if you want to specify a customized stylesheet.- -
epub.css
: can be useful if you want to specify a customized stylesheet.+
epub.highlight.theme
: similar torendering.highlight.theme
but only sets a theme for EPUB output.
epub.highlight.theme
: similar torendering.highlight.theme
but only sets a theme for EPUB output.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.
+3.3.9. Resources options
+These options allow to embed additional files for some formats (currently, only EPUB). This can be useful for embedding fonts.
+3.3.9.1.
+resources.files
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 containingfont1.otf
andfont2.otf
,It is also possible to specify a directory (or multiple directories). So if you have a
fonts
directories containingfont1.otf
andfont2.otf
,resources.files: [fonts] -will be equivalent to:
+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 theresources.files
in the first example above will searchfont1.otf
andfont2.otf
in the same directory than the.book
file, and will copy them todata/font1.otf
anddata/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 assumingfonts/
containsfont1.otf
andfont2.otf
default: not set
+3.3.9.2.
+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 theresources.files
in the first example above will searchfont1.otf
andfont2.otf
in the same directory than the.book
file, and will copy them todata/font1.otf
anddata/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 assumingfonts/
containsfont1.otf
andfont2.otf
resources.files: [fonts] resources.path: data -will copy these two files to
-data/fonts/font1.otf
anddata/fonts/font2.otf
(and notdata/font1.otf
anddata/font2.otf
).Similarly, the whole path of
+resources.files
is copied, sowill copy these two files to
+data/fonts/font1.otf
anddata/fonts/font2.otf
(and notdata/font1.otf
anddata/font2.otf
).Similarly, the whole path of
resources.files
is copied, soresources.files: [fonts/font1.otf, fonts/font2.otf] -will yield the same result.
-default:
+data
will yield the same result.
+default:
data
3.4. Full list of options
-Here is the complete list of options. You can always look at it by running
-crowbook --list-options
orcrowbook -l
.Metadata
+Here is the complete list of options. You can always look at it by running
+crowbook --list-options
orcrowbook -l
.Note that these options have a type, which in most case should be pretty straightforward (a boolean can be
+true
orfalse
, 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). Thepath
type might puzzle you a bit, but it’s equivalent to a string, except Crowbook will consider it relatively to the book file. Thetemplate path
type is just thepath
of a template. Metadata are just strings.3.4.1. Metadata
+3.4.1.1.
author
-
- -- -
-
author
-
-type: metadata
+- -
type: metadata
default value:
+""
- -
default value:
""
Author of the book
+Author of the book
+
title
3.4.1.2.
title
- @@ -1301,1126 +1998,988 @@ output.epub: Title of the book
type: metadata
- -
+
lang
3.4.1.3.
lang
-
-type: metadata
+- -
type: metadata
default value:
+en
- -
default value:
en
Language of the book
+Language of the book
- -
+
subject
3.4.1.4.
subject
-
-type: metadata
+- -
type: metadata
default value:
+not set
- -
default value:
not set
Subject of the book (used for EPUB metadata)
+Subject of the book (used for EPUB metadata)
- -
+
description
3.4.1.5.
description
-
+type: metadata
+- +
type: metadata
+- +
default value:
+not set
- +
Description of the book (used for EPUB metadata)
+3.4.1.6.
+cover
+
-type: path
- -
default value:
not set
Description of the book (used for EPUB metadata)
+Path to the cover of the book
- - -
+
cover
3.4.2. Additional metadata
+3.4.2.1.
subtitle
-
-type: path
+- -
type: metadata
default value:
+not set
- -
default value:
not set
Path to the cover of the book
+Subtitle of the book
Additional metadata
+3.4.2.2.
license
-
- -
-
subtitle
-
+type: metadata
+- -
type: metadata
default value:
+not set
- -
default value:
not set
Subtitle of the book
+License of the book. This information will be displayed on PDF documents
3.4.2.3.
+version
+
+- -
type: metadata
+
license
- +
default value:
+not set
- +
Version of the book
+3.4.2.4.
date
-
type: metadata
- -
default value:
not set
License of the book. This information will be displayed on PDF documents
+Date the book was revised
- -
+
version
3.4.3. Output options
+3.4.3.1.
output
-
-type: metadata
+- -
type: list of strings
default value:
+not set
- -
default value:
not set
Version of the book
+Specify a list of output formats to render
- -
+
date
3.4.3.2.
output.epub
-
+type: metadata
+- -
type: path
default value:
+not set
- -
default value:
not set
Date the book was revised
+Output file name for EPUB rendering
3.4.3.3.
+output.html
+
-- +
type: path
+- +
default value:
+not set
Output file name for HTML rendering
Output options
+3.4.3.4.
output.html.dir
-
-- -
-
output
-
-type: list of strings
+type: path
- -
default value:
not set
Specify a list of output formats to render
+Output directory name for HTML rendering
- -
+
output.epub
3.4.3.5.
output.tex
-
-type: path
+- -
type: path
default value:
+not set
- -
default value:
not set
Output file name for EPUB rendering
+Output file name for LaTeX rendering
- -
+
output.html
3.4.3.6.
output.pdf
-
+type: path
+- -
type: path
default value:
+not set
- -
default value:
not set
Output file name for HTML rendering
+Output file name for PDF rendering
3.4.3.7.
+output.odt
+
+- -
type: path
+
output.html.dir
- +
default value:
+not set
- +
Output file name for ODT rendering
+3.4.3.8.
output.html.if
-
type: path
- -
default value:
not set
Output directory name for HTML rendering
+Output file name for HTML (interactive fiction) rendering
- -
+
output.tex
3.4.3.9.
output.base_path
-
-type: path
+- -
type: path
default value:
+not set
- -
default value:
""
Output file name for LaTeX rendering
+Directory where those output files will we written
- -
+
output.pdf
3.4.4. Rendering options
+3.4.4.1.
rendering.highlight
-
-type: path
+- -
type: string
default value:
+not set
- -
default value:
syntect
Output file name for PDF rendering
+If/how highligh code blocks. Possible values: “syntect” (default, performed at runtime), “highlight.js” (HTML-only, uses Javascript), “none”
- -
+
output.odt
3.4.4.2.
rendering.highlight.theme
-
-type: path
+- -
type: string
default value:
+not set
- -
default value:
InspiredGitHub
Output file name for ODT rendering
+Theme for syntax highlighting (if rendering.highlight is set to ‘syntect’)
- -
+
output.html.if
3.4.4.3.
rendering.initials
-
-type: path
+- -
type: boolean
default value:
+not set
- -
default value:
false
Output file name for HTML (interactive fiction) rendering
+Use initials (‘lettrines’) for first letter of a chapter (experimental)
- -
+
output.base_path
3.4.4.4.
rendering.inline_toc
-
-type: path
+- -
type: boolean
default value:
+""
- -
default value:
false
Directory where those output files will we written
+Display a table of content in the document
Rendering options
+3.4.4.5.
rendering.inline_toc.name
-
++
rendering.highlight
- +
type: string
+- +
default value:
+"{{{loc_toc}}}"
- +
Name of the table of contents if it is displayed in document
+3.4.4.6.
+rendering.num_depth
+
+- +
type: integer
+- +
default value:
+1
- +
The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
+3.4.4.7.
rendering.chapter
-
- -
type: string
default value:
+syntect
- -
default value:
not set
If/how highligh code blocks. Possible values: “syntect” (default, performed at runtime), “highlight.js” (HTML-only, uses Javascript), “none”
+How to call chapters
- -
+
rendering.highlight.theme
3.4.4.8.
rendering.part
-
-type: string
+- -
type: string
default value:
+InspiredGitHub
- -
default value:
not set
Theme for syntax highlighting (if rendering.highlight is set to ‘syntect’)
+How to call parts (or ‘books’, ‘episodes’, ...
- -
+
rendering.initials
3.4.4.9.
rendering.chapter.roman_numerals
-
+type: boolean
+- -
type: boolean
default value:
+false
- -
default value:
false
Use initials (‘lettrines’) for first letter of a chapter (experimental)
+If set to true, display chapter number with roman numerals
3.4.4.10.
+rendering.part.roman_numerals
+
+- -
type: boolean
+
rendering.inline_toc
- +
default value:
+true
- +
If set to true, display part number with roman numerals
+3.4.4.11.
rendering.part.reset_counter
-
- -
type: boolean
default value:
+false
- -
default value:
true
Display a table of content in the document
+If set to true, reset chapter number at each part
- -
+
rendering.inline_toc.name
3.4.4.12.
rendering.chapter.template
-
-type: string
+- -
type: string
default value:
+"{{{loc_toc}}}"
- -
default value:
"{{{number}}}. {{{chapter_title}}}"
Name of the table of contents if it is displayed in document
+Naming scheme of chapters, for TOC
- -
+
rendering.num_depth
3.4.4.13.
rendering.part.template
-
-type: integer
+- -
type: string
default value:
+1
- -
default value:
"{{{number}}}. {{{part_title}}}"
The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
+Naming scheme of parts, for TOC
- -
+
rendering.chapter
3.4.5. Special option
+3.4.5.1.
import
-
+type: string
+- +
type: path
+- +
default value:
+not set
- +
Import another book configuration file
+3.4.6. HTML options
+3.4.6.1.
+html.icon
+
-type: path
- -
default value:
not set
How to call chapters
+Path to an icon to be used for the HTML files(s)
- -
+
rendering.part
3.4.6.2.
html.highlight.theme
-
-type: string
+- -
type: string
default value:
+not set
- -
default value:
not set
How to call parts (or ‘books’, ‘episodes’, ...
+If set, set theme for syntax highlighting for HTML output (syntect only)
- -
+
rendering.chapter.roman_numerals
3.4.6.3.
html.header
-
-type: boolean
+- -
type: string
default value:
+false
- -
default value:
not set
If set to true, display chapter number with roman numerals
+Custom header to display at the beginning of html file(s)
- -
+
rendering.part.roman_numerals
3.4.6.4.
html.footer
-
-type: boolean
+- -
type: string
default value:
+true
- -
default value:
not set
If set to true, display part number with roman numerals
+Custom footer to display at the end of HTML file(s)
- -
+
rendering.part.reset_counter
3.4.6.5.
html.css
-
-type: boolean
+- -
type: template path
default value:
+true
- -
default value:
not set
If set to true, reset chapter number at each part
+Path of a stylesheet for HTML rendering
- -
+
rendering.chapter.template
3.4.6.6.
html.css.add
-
-type: string
+- -
type: string
default value:
+"{{{number}}}. {{{chapter_title}}}"
- -
default value:
not set
Naming scheme of chapters, for TOC
+Some inline CSS added to the stylesheet template
+
rendering.part.template
3.4.6.7.
html.css.colors
-
+type: string
+- -
type: template path
default value:
+"{{{number}}}. {{{part_title}}}"
- -
default value:
not set
Naming scheme of parts, for TOC
+Path of a stylesheet for the colors for HTML
3.4.6.8.
+html.js
+
-- +
type: template path
+- +
default value:
+not set
Path of a javascript file
Special option
+3.4.6.9.
html.css.print
-
-
import
-
+type: path
+- -
type: template path
default value:
+not set
- -
default value:
not set
Import another book configuration file
+Path of a media print stylesheet for HTML rendering
3.4.6.10.
+html.highlight.js
+
-- +
type: template path
+- +
default value:
+not set
Set another highlight.js version than the bundled one
HTML options
+3.4.6.11.
html.highlight.css
-
-- -
-
html.icon
-
-type: path
+- -
type: template path
default value:
+not set
- -
default value:
not set
Path to an icon to be used for the HTML files(s)
+Set another highlight.js CSS theme than the default one
- -
+
html.highlight.theme
3.4.6.12.
html.side_notes
-
-type: string
+- -
type: boolean
default value:
+not set
- -
default value:
false
If set, set theme for syntax highlighting for HTML output (syntect only)
+Display footnotes as side notes in HTML/Epub (experimental)
- -
+
html.header
3.4.6.13.
html.escape_nb_spaces
-
-type: string
+- -
type: boolean
default value:
+not set
- -
default value:
true
Custom header to display at the beginning of html file(s)
+Replace unicode non breaking spaces with HTML entities and CSS
- -
+
html.footer
3.4.6.14.
html.chapter.template
-
-type: string
+- -
type: string
default value:
+not set
- -
default value:
"<h1 id = 'link-{{{link}}}'>{{#has_number}}<span class = 'chapter-header'>{{{header}}} {{{number}}}</span>{{#has_title}}<br />{{/has_title}}{{/has_number}}{{{title}}}</h1>"
Custom footer to display at the end of HTML file(s)
+Inline template for HTML chapter formatting
- -
+
html.css
3.4.6.15.
html.part.template
-
-type: template path
+- -
type: string
default value:
+not set
- -
default value:
"<h2 class = 'part'>{{{header}}} {{{number}}}</h2> <h1 id = 'link-{{{link}}}' class = 'part'>{{{title}}}</h1>"
Path of a stylesheet for HTML rendering
+Inline template for HTML part formatting
- -
+
html.css.add
3.4.7. Standalone HTML options
+3.4.7.1.
html.standalone.template
-
-type: string
+- -
type: template path
default value:
+not set
- -
default value:
not set
Some inline CSS added to the stylesheet template
+Path of an HTML template for standalone HTML
- -
+
html.css.colors
3.4.7.2.
html.standalone.one_chapter
-
-type: template path
+- -
type: boolean
default value:
+not set
- -
default value:
false
Path of a stylesheet for the colors for HTML
+Display only one chapter at a time (with a button to display all)
- -
+
html.js
3.4.7.3.
html.standalone.js
-
+type: template path
+- +
type: template path
+- +
default value:
+not set
- +
Path of a javascript file
+3.4.8. Multifile HTML options
+3.4.8.1.
+html.dir.template
+
+- +
type: template path
+- +
default value:
+not set
- +
Path of a HTML template for multifile HTML
+3.4.9. Interactive fiction HTML options
+3.4.9.1.
+html.if.js
+
+- +
type: template path
+- +
default value:
+not set
- +
Path of a javascript file
+3.4.9.2.
+html.if.new_turn
+
-type: string
- -
default value:
not set
Path of a javascript file
+Javascript code that will be run at the beginning of each segment
- -
+
html.css.print
3.4.9.3.
html.if.end_turn
-
-type: template path
+- -
type: string
default value:
+not set
- -
default value:
not set
Path of a media print stylesheet for HTML rendering
+Javascript code that will be run at the end of each segment
- -
+
html.highlight.js
3.4.9.4.
html.if.new_game
-
-type: template path
+- -
type: template path
default value:
+not set
- -
default value:
not set
Set another highlight.js version than the bundled one
+Javascript code that will be run at the beginning of a ‘game’
- -
+
html.highlight.css
3.4.10. EPUB options
+3.4.10.1.
epub.version
-
+type: template path
+- +
type: integer
+- +
default value:
+2
- +
EPUB version to generate (2 or 3)
+3.4.10.2.
+epub.highlight.theme
+
-type: string
- -
default value:
not set
Set another highlight.js CSS theme than the default one
+If set, set theme for syntax highlighting for EPUB output (syntect only)
- -
+
html.side_notes
3.4.10.3.
epub.css
-
-type: boolean
+- -
type: template path
default value:
+false
- -
default value:
not set
Display footnotes as side notes in HTML/Epub (experimental)
+Path of a stylesheet for EPUB
- -
+
html.escape_nb_spaces
3.4.10.4.
epub.css.add
-
-type: boolean
+- -
type: string
default value:
+true
- -
default value:
not set
Replace unicode non breaking spaces with HTML entities and CSS
+Inline CSS added to the EPUB stylesheet template
- -
+
html.chapter.template
3.4.10.5.
epub.chapter.xhtml
-
-type: string
+- -
type: template path
default value:
+"<h1 id = 'link-{{{link}}}'>{{#has_number}}<span class = 'chapter-header'>{{{header}}} {{{number}}}</span>{{#has_title}}<br />{{/has_title}}{{/has_number}}{{{title}}}</h1>"
- -
default value:
not set
Inline template for HTML chapter formatting
+Path of an xhtml template for each chapter
- -
+
html.part.template
3.4.10.6.
epub.toc.extras
-
-type: string
+- -
type: boolean
default value:
+"<h2 class = 'part'>{{{header}}} {{{number}}}</h2> <h1 id = 'link-{{{link}}}' class = 'part'>{{{title}}}</h1>"
- -
default value:
true
Inline template for HTML part formatting
+Add ‘Title’ and (if set) ‘Cover’ in the EPUB table of contents
Standalone HTML options
+3.4.10.7.
epub.escape_nb_spaces
-
- -
-
html.standalone.template
-
-type: template path
+- -
type: boolean
default value:
+not set
- -
default value:
true
Path of an HTML template for standalone HTML
+Replace unicode non breaking spaces with HTML entities and CSS
- -
+
html.standalone.one_chapter
3.4.11. LaTeX options
+3.4.11.1.
tex.highlight.theme
-
-type: boolean
+- -
type: string
default value:
+false
- -
default value:
not set
Display only one chapter at a time (with a button to display all)
+If set, set theme for syntax highlighting for LaTeX/PDF output (syntect only)
+
html.standalone.js
3.4.11.2.
tex.links_as_footnotes
-
+type: template path
+- -
type: boolean
default value:
+not set
- -
default value:
true
Path of a javascript file
+Add foontotes to URL of links so they are readable when printed
3.4.11.3.
+tex.command
+
-- +
type: string
+- +
default value:
+xelatex
LaTeX command to use for generating PDF
Multifile HTML options
+3.4.11.4.
tex.template
-
-
html.dir.template
-
+type: template path
+- -
type: template path
default value:
+not set
- -
default value:
not set
Path of a HTML template for multifile HTML
+Path of a LaTeX template file
3.4.11.5.
+tex.template.add
+
-- +
type: string
+- +
default value:
+not set
Inline code added in the LaTeX template
Interactive fiction HTML options
+3.4.11.6.
tex.class
-
- -
-
html.if.js
-
-type: template path
+- -
type: string
default value:
+not set
- -
default value:
book
Path of a javascript file
+LaTeX class to use
- -
+
html.if.new_turn
3.4.11.7.
tex.paper.size
-
-type: string
+- -
type: string
default value:
+not set
- -
default value:
a5paper
Javascript code that will be run at the beginning of each segment
+Specifies the size of the page.
- -
+
html.if.end_turn
3.4.11.8.
tex.margin.left
-
-type: string
+- -
type: string
default value:
+not set
- -
default value:
not set
Javascript code that will be run at the end of each segment
+Specifies left margin (note that with book class left and right margins are reversed for odd pages, thus the default value is 1.5cm for book class and 2cm else)
+
html.if.new_game
3.4.11.9.
tex.margin.right
-
+type: template path
+- -
type: string
default value:
+not set
- -
default value:
not set
Javascript code that will be run at the beginning of a ‘game’
+Specifies right margin(note that with book class left and right margins are reversed for odd pages, thus the default value is 2.5cm for book class and 2cm else)
3.4.11.10.
+tex.margin.top
+
-- +
type: string
+- +
default value:
+"2cm"
Specifies top margin
EPUB options
+3.4.11.11.
tex.margin.bottom
-
-- -
-
epub.version
-
-type: integer
+- -
type: string
default value:
+2
- -
default value:
"1.5cm"
EPUB version to generate (2 or 3)
+Specifies left margin
- -
+
epub.highlight.theme
3.4.11.12.
tex.title
-
-type: string
+- -
type: boolean
default value:
+not set
- -
default value:
true
If set, set theme for syntax highlighting for EPUB output (syntect only)
+If true, generate a title with \maketitle
- -
+
epub.css
3.4.11.13.
tex.font.size
-
-type: template path
+- -
type: integer
default value:
+not set
- -
default value:
not set
Path of a stylesheet for EPUB
+Specify latex font size (in pt, 10 (default), 11, or 12 are accepted)
- -
+
epub.css.add
3.4.11.14.
tex.hyperref
-
-type: string
+- -
type: boolean
default value:
+not set
- -
default value:
true
Inline CSS added to the EPUB stylesheet template
+If disabled, don’t try to find references inside the document
- -
+
epub.chapter.xhtml
3.4.11.15.
tex.stdpage
-
-type: template path
+- -
type: boolean
default value:
+not set
- -
default value:
false
Path of an xhtml template for each chapter
+If set to true, use ‘stdpage’ package to format a manuscript according to standards
- -
+
epub.toc.extras
3.4.12. Resources option
+3.4.12.1.
resources.files
-
-type: boolean
+- -
type: list of strings
default value:
+true
- -
default value:
not set
Add ‘Title’ and (if set) ‘Cover’ in the EPUB table of contents
+Whitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
- -
+
epub.escape_nb_spaces
3.4.12.2.
resources.out_path
-
+type: boolean
+- -
type: path
default value:
+true
- -
default value:
data
Replace unicode non breaking spaces with HTML entities and CSS
+Paths where additional resources should be copied in the EPUB file or HTML directory
3.4.12.3.
+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.
LaTeX options
+3.4.12.4.
resources.base_path.links
-
-- -
-
tex.highlight.theme
-
+type: string
+- -
type: path
default value:
+not set
- -
default value:
not set
If set, set theme for syntax highlighting for LaTeX/PDF output (syntect only)
+Set base path but only for links. Useless if resources.base_path is set
3.4.12.5.
+resources.base_path.images
+
+- -
type: path
+
tex.links_as_footnotes
- +
default value:
+.
- +
Set base path but only for images. Useless if resources.base_path is set
+3.4.12.6.
+resources.base_path.files
+
+- +
type: path
+- +
default value:
+.
- +
Set base path but only for additional files. Useless if resources.base_path is set.
+3.4.12.7.
+resources.base_path.templates
+
+- +
type: path
+- +
default value:
+.
- +
Set base path but only for templates files. Useless if resources.base_path is set
+3.4.13. Input options
+3.4.13.1.
input.clean
-
type: boolean
- -
default value:
true
Add foontotes to URL of links so they are readable when printed
+Toggle typographic cleaning of input markdown according to lang
- -
+
tex.command
3.4.13.2.
input.clean.smart_quotes
-
-type: string
+- -
type: boolean
default value:
+xelatex
- -
default value:
true
LaTeX command to use for generating PDF
+If enabled, tries to replace vertical quotations marks to curly ones
- -
+
tex.template
3.4.13.3.
input.clean.ligature.dashes
-
-type: template path
+- -
type: boolean
default value:
+not set
- -
default value:
false
Path of a LaTeX template file
+If enabled, replaces ‘--’ to en dash ('–') and ‘---’ to em dash ('—')
- -
+
tex.template.add
3.4.13.4.
input.clean.ligature.guillemets
-
-type: string
+- -
type: boolean
default value:
+not set
- -
default value:
false
Inline code added in the LaTeX template
+If enabled, replaces ‘<<’ and ‘>>’ to french “guillemets” ('«’ and ‘»’)
- -
+
tex.class
3.4.13.5.
input.yaml_blocks
-
-type: string
+- -
type: boolean
default value:
+book
- -
default value:
false
LaTeX class to use
+Enable inline YAML blocks to override options set in config file
- -
+
tex.paper.size
3.4.14. Crowbook options
+3.4.14.1.
crowbook.html_as_text
-
+type: string
+- -
type: boolean
default value:
+a5paper
- -
default value:
true
Specifies the size of the page.
+Consider HTML blocks as text. This avoids having
<foo>
being considered as HTML and thus ignored.3.4.14.2.
+crowbook.markdown.superscript
+
+- -
type: boolean
+
tex.margin.left
- +
default value:
+false
- +
If enabled, allow support for superscript and subscript using respectively fooup and bar
+downsyntax.3.4.14.3.
+crowbook.temp_dir
+
+- +
type: path
+- +
default value:
+(empty string)
- +
Path where to create a temporary directory (default: uses result from Rust’s std::env::temp_dir())
+3.4.14.4.
crowbook.zip.command
-
- -
type: string
default value:
+not set
- -
default value:
zip
Specifies left margin (note that with book class left and right margins are reversed for odd pages, thus the default value is 1.5cm for book class and 2cm else)
+Command to use to zip files (for EPUB/ODT)
- -
+
tex.margin.right
3.4.15. Output options (for proofreading)
+3.4.15.1.
output.proofread.html
-
-type: string
+- -
type: path
default value:
+not set
- -
default value:
not set
Specifies right margin(note that with book class left and right margins are reversed for odd pages, thus the default value is 2.5cm for book class and 2cm else)
+Output file name for HTML rendering with proofread features
- -
+
tex.margin.top
3.4.15.2.
output.proofread.html.dir
-
-type: string
+- -
type: path
default value:
+"2cm"
- -
default value:
not set
Specifies top margin
+Output directory name for HTML rendering with proofread features
- -
+
tex.margin.bottom
3.4.15.3.
output.proofread.pdf
-
-type: string
+- -
type: path
default value:
+"1.5cm"
- -
default value:
not set
Specifies left margin
+Output file name for PDF rendering with proofread features
- -
+
tex.title
3.4.16. Proofreading options (only for
+output.proofread.*
targets)3.4.16.1.
proofread
-
-type: boolean
+- -
type: boolean
default value:
+true
- -
default value:
false
If true, generate a title with \maketitle
+If set to false, will disactivate proofreading even if one of output.proofread.x is present
- -
+
tex.font.size
3.4.16.2.
proofread.languagetool
-
-type: integer
+- -
type: boolean
default value:
+not set
- -
default value:
false
Specify latex font size (in pt, 10 (default), 11, or 12 are accepted)
+If true, try to use language tool server to grammar check the book
- -
+
tex.hyperref
3.4.16.3.
proofread.languagetool.port
-
-type: boolean
+- -
type: integer
default value:
+true
- -
default value:
8081
If disabled, don’t try to find references inside the document
+Port to connect to languagetool-server
- -
+
tex.stdpage
3.4.16.4.
proofread.grammalecte
-
-type: boolean
+- -
type: boolean
default value:
+false
- -
default value:
false
If set to true, use ‘stdpage’ package to format a manuscript according to standards
+If true, try to use grammalecte server to grammar check the book
Resources option
+3.4.16.5.
proofread.grammalecte.port
-
++
resources.files
- +
type: integer
+- +
default value:
+8080
- +
Port to connect to grammalecte server
+3.4.16.6.
proofread.repetitions
-
-type: list of strings
+- -
type: boolean
default value:
+not set
- -
default value:
false
Whitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
+If set to true, use Caribon to detect repetitions
- -
+
resources.out_path
3.4.16.7.
proofread.repetitions.max_distance
-
-type: path
+- -
type: integer
default value:
+data
- -
default value:
25
Paths where additional resources should be copied in the EPUB file or HTML directory
+Max distance between two occurences so it is considered a repetition
- -
+
resources.base_path
3.4.16.8.
proofread.repetitions.fuzzy
-
-type: path
+- -
type: boolean
default value:
+not set
- -
default value:
true
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.
+Enable fuzzy string matching
- -
+
resources.base_path.links
3.4.16.9.
proofread.repetitions.fuzzy.threshold
-
-type: path
+- -
type: float
default value:
+not set
- -
default value:
0.2
Set base path but only for links. Useless if resources.base_path is set
+Max threshold of differences to consider two strings a repetition
- -
+
resources.base_path.images
3.4.16.10.
proofread.repetitions.ignore_proper
-
-type: path
+- -
type: boolean
default value:
+.
- -
default value:
true
Set base path but only for images. Useless if resources.base_path is set
+Ignore proper nouns for repetitions
- -
+
resources.base_path.files
3.4.16.11.
proofread.repetitions.threshold
-
-type: path
+- -
type: float
default value:
+.
- -
default value:
2.0
Set base path but only for additional files. Useless if resources.base_path is set.
+Threshold to detect a repetition
- -
-
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.html_as_text
-
-- -
type: boolean
-- -
default value:
-true
- -
Consider HTML blocks as text. This avoids having
-<foo>
being considered as HTML and thus ignored.- -
-
crowbook.markdown.superscript
-
-- -
type: boolean
-- -
default value:
-false
- -
If enabled, allow support for superscript and subscript using respectively fooup and bar
-downsyntax.- -
-
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)
-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.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.grammalecte
-
-- -
type: boolean
-- -
default value:
-false
- -
If true, try to use grammalecte server to grammar check the book
-- -
-
proofread.grammalecte.port
-
-- -
type: integer
-- -
default value:
-8080
- -
Port to connect to grammalecte 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
orfalse
, 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). Thepath
type might puzzle you a bit, but it’s equivalent to a string, except Crowbook will consider it relatively to the book file. Thetemplate path
type is just thepath
of a template. Metadata are just strings.
Chapter 4
Markdown format
Crowbook uses pulldown-cmark, which is an implementation of CommonMark, so for more information on Markdown syntax, you can refer to those websites.
-However, pulldown-cmark also implements a handful of unofficial extensions, and Crowbook also adds its own variants, so there are a few syntax elements that are not covered by the CommonMark reference.
-4.1. Tables
-Tables can be included in your Markdown file. E.g.:
+Chapter 4
Markdown format
crowbook
uses pulldown-cmark, which is an implementation of CommonMark, so for more information on Markdown syntax, you can refer to those websites.
However, pulldown-cmark
also implements a handful of unofficial extensions, and crowbook
also adds its own variants, so there are a few syntax elements that are not covered by the CommonMark
reference.
4.1. Tables
+Tables can be included in your Markdown file.
+E.g.:
| Author | Book | |--------------------|----------------------------| | Anne Rice | Interview With the Vampire | | Terry Pratchett | Hogfather | | George Martin | A Dance with Dragons | -
will render as
+will render as
Template-dependent values
-Crowbook also exports some additional fields for some templates, see below.
+5.3.3. Template-dependent values
+Crowbook also exports some additional fields for some templates, see below.