Crowbook User Guide 0.15.0
+Crowbook User Guide 0.15.0
Crowbook User Guide
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 @@1.1. Example
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.
1.4. Quick tour
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 @@
1.7. Acknowledgements
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 @@1.11. License
Chapter 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 @@2.1.
+ chapter_3.md--create
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 @@2.2.
--- Content of the story in Markdown. ---single
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
+--singleor-ssets the default LaTeX class of the book toarticleinstead 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
--singleor-ssets the default LaTeX class of the book toarticleinstead ofbook.2.3.
---setUsage:
-crowbook <BOOK> --set [KEY] [VALUE]...This argument takes a list of
+KEYVALUEpairs 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
KEYVALUEpairs 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-optionsUsage:
-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-templateUsage:
-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.
---statsUsage:
-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.
---proofreadUsage:
-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.
---autographUsage:
-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 @@Example
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.
---verboseUsage:
-crowbook <BOOK> --verboseIf 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.
---toUsage:
-crowbook <BOOK> --to [FORMAT](or
-crowbook <BOOK> -t [FORMAT])Generate only the specified format.
-FORMATmust be eitherepub,html,html.dir,odtortex.If an output file for the format is not specified in the book configuration file,
-crowbookwill 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--outputoption.Examples
+Usage:
+crowbook <BOOK> --to [FORMAT] +or:
+crowbook <BOOK> -t [FORMAT] +Generate only the specified format.
+FORMATmust be eitherepub,html,html.dir,odtortex.If an output file for the format is not specified in the book configuration file,
+crowbookwill 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--outputoption.2.10.1. Examples
crowbook --to html foo.book -will generate some HTML, and prints it either to the file specified by
+output.htmlinfoo.book, or to stdout if it is not specified.will generate some HTML, and prints it either to the file specified by
output.htmlinfoo.book, or to stdout if it is not specified.crowbook --to pdf --output foo.pdf foo.book -will generate a
+foo.pdffile.will generate a
foo.pdffile.2.11.
---outputUsage:
-crowbook <BOOK> --to <FORMAT> --output <FILE>(or
-crowbook -t <FORMAT> -o <FILE> <BOOK>)Specifies an output file. Only valid when
+--tois used.Usage:
+crowbook <BOOK> --to <FORMAT> --output <FILE> +or:
+crowbook -t <FORMAT> -o <FILE> <BOOK> +Specifies an output file. Only valid when
--tois used.2.12.
---langUsage:
-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
-LANGenvironment 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 --helpwill display Crowbook’s help message in french.
-Note that this argument has nothing to do with the
+langoption 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
+LANGenvironment 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
langoption 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 @@Chapter 3
- epilogue.md -
The conf + chapter_3.md + chapter_4.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 @@3.1. Configuration in an inline YAML block
# 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_blocksis 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_blocksis 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.mdincludes a numbered chapter.- -
+ file_name.mdincludes a numbered chapter.+
- file_name.mdincludes an unnumbered chapter.- -
- file_name.mdincludes an unnumbered chapter.+
! file_name.mdincludes 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.mdincludes 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.mdspecifies the number for a chapter.- -
42. file_name.mdspecifies 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 @@3.2. The list of files
+ 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.bookwithout 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.bookwithout 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 @@Parts
+ 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 @@Parts
+ 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.mdwill be displayed as a level-2 header in the book, and a level-1 header insubsection.mdas 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.mdwill be displayed as a level-2 header in the book, and a level-1 header insubsection.mdas 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
-titleto"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
-xis 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
+titleto"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.(wherexis 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_GBoren,fr_FR, orfr...- -
lang, the language of the book. The unicode language code should be used, e.g.en_GBoren,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
dateYou can define your own metadata by starting an option name with
-metadata.foo.All metadata are accessible from templates, see Templates.
-The
-importspecial optionThe special
+importoption 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.bookandbar.book, you can create acommon.bookfile: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
+importspecial optionThe special
importoption 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.bookandbar.book, you can create acommon.bookfile: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.epubwill be generated insome/dir, not in your current directory.Crowbook will try to generate each of the
+output.xxxfiles that are specified. That means that you’ll have to set at least one of those if you want a call to+
foo.epubwill be generated insome/dir, not in your current directory.Crowbook will try to generate each of the
output.xxxfiles 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
---toand--outputargument on the command line).Note that some formats depend on some commands being installed on your system. Most notably, Crowbook depends on LaTeX (
-xelatexby 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 thezipcommand 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
+--toand--outputargument on the command line).Note that some formats depend on some commands being installed on your system. Most notably, Crowbook depends on LaTeX (
+xelatexby 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 thezipcommand 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
-outputoptionSetting 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
+outputoption:(There are other output options for generating proofreading files, see Proofreading, and interactive fiction, see Interactive fiction.)
+3.3.3.1. The
+outputoptionSetting 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
outputoption: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.htmlandmy_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.htmlandmy_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_pathAdditionally, the
+output.base_pathoption 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_pathAdditionally, the
output.base_pathoption 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.jsfor HTML rendering, and will not perform any syntax highlighting for other output formats.- -
highlight.js: this will use (and embed)highlight.jsfor 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
+syntectsupport, it will default tononeif you try to use it.If your version of
crowbook(as is the case for Windows builds) isn’t built withsyntectsupport, it will default tononeif you try to use it.-
-+
rendering.highlight.theme: only used ifrendering.highlightis set tosyntect, selects the theme to use for syntax highlighting. Default is “InspiredGitHub”. Valid theme names are:- -
rendering.highlight.theme: only used ifrendering.highlightis 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.,1will only number chapters, while2will number chapters, sections, but not anything below that.6is 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.,1will only number chapters, while2will number chapters, sections, but not anything below that.6is 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.chapterandrendering.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.chapterandrendering.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_numeralsandrendering.chapter.roman_numerals: these two booleans allow you to specify if you want roman numerals for part or chapter numbers (default istruefor part numbers, andfalsefor chapter numbers).- -
rendering.part.roman_numeralsandrendering.chapter.roman_numerals: these two booleans allow you to specify if you want roman numerals for part or chapter numbers (default istruefor part numbers, andfalsefor 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 tofalseif you don’t want your chapter numbers to start again at 1 at each part.
rendering.part.reset_counter: set it tofalseif 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 afaviconfor the page.- -
html.icon: allows to set afaviconfor the page.+
html.headerandhtml.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.headerandhtml.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.themebut only sets the theme for HTML output.
html.highlight.theme: is similar torendering.highlight.themebut 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.sizeandtex.font.size: (defaulta5paperand10pt) allows to modify the page and font size.- -
tex.paper.sizeandtex.font.size: (defaulta5paperand10pt) allows to modify the page and font size.+
tex.margin.left,tex.margin.right,tex.margin.topandtex.margin.bottom: specify the margin of the page.- -
tex.margin.left,tex.margin.right,tex.margin.topandtex.margin.bottom: specify the margin of the page.+
tex.links_as_footnotes: can be set tofalseif 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 tofalseif 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.themebut only sets a theme for EPUB output.
epub.highlight.theme: similar torendering.highlight.themebut 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.filesA 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
+fontsdirectories containingfont1.otfandfont2.otf,It is also possible to specify a directory (or multiple directories). So if you have a
fontsdirectories containingfont1.otfandfont2.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.filesin the first example above will searchfont1.otfandfont2.otfin the same directory than the.bookfile, and will copy them todata/font1.otfanddata/font2.otfin 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.otfandfont2.otfdefault: not set
+3.3.9.2.
+resources.out_pathThis option determine where (in which directory), in the resulting document, those files will be copied. The default is
+data, so by default theresources.filesin the first example above will searchfont1.otfandfont2.otfin the same directory than the.bookfile, and will copy them todata/font1.otfanddata/font2.otfin 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.otfandfont2.otfresources.files: [fonts] resources.path: data -will copy these two files to
-data/fonts/font1.otfanddata/fonts/font2.otf(and notdata/font1.otfanddata/font2.otf).Similarly, the whole path of
+resources.filesis copied, sowill copy these two files to
+data/fonts/font1.otfanddata/fonts/font2.otf(and notdata/font1.otfanddata/font2.otf).Similarly, the whole path of
resources.filesis copied, soresources.files: [fonts/font1.otf, fonts/font2.otf] -will yield the same result.
-default:
+datawill yield the same result.
+default:
data3.4. Full list of options
-Here is the complete list of options. You can always look at it by running
-crowbook --list-optionsorcrowbook -l.Metadata
--
-- -
+
authorHere is the complete list of options. You can always look at it by running
+crowbook --list-optionsorcrowbook -l.Note that these options have a type, which in most case should be pretty straightforward (a boolean can be
+trueorfalse, 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). Thepathtype might puzzle you a bit, but it’s equivalent to a string, except Crowbook will consider it relatively to the book file. Thetemplate pathtype is just thepathof a template. Metadata are just strings.3.4.1. Metadata
+3.4.1.1.
author-
-type: metadata
+- -
type: metadata
default value:
+""- -
default value:
""Author of the book
+Author of the book
- -
+
title3.4.1.2.
title-
- @@ -1301,1126 +1998,988 @@
type: metadata
Metadata
Title of the book
- -
+
lang3.4.1.3.
lang-
-type: metadata
+- -
type: metadata
default value:
+en- -
default value:
enLanguage of the book
+Language of the book
- -
+
subject3.4.1.4.
subject-
-type: metadata
+- -
type: metadata
default value:
+not set- -
default value:
not setSubject of the book (used for EPUB metadata)
+Subject of the book (used for EPUB metadata)
- -
+
description3.4.1.5.
description-
-type: metadata
+- -
type: metadata
default value:
+not set- -
default value:
not setDescription of the book (used for EPUB metadata)
+Description of the book (used for EPUB metadata)
+
cover3.4.1.6.
cover-
+- -
type: path
-default value:
+not set- -
type: path
Path to the cover of the book
+- -
default value:
not setPath to the cover of the book
Additional metadata
+3.4.2. Additional metadata
+3.4.2.1.
subtitle-
-- -
-
subtitle-
-type: metadata
+- -
type: metadata
default value:
+not set- -
default value:
not setSubtitle of the book
+Subtitle of the book
- -
+
license3.4.2.2.
license-
-type: metadata
+- -
type: metadata
default value:
+not set- -
default value:
not setLicense of the book. This information will be displayed on PDF documents
+License of the book. This information will be displayed on PDF documents
- -
+
version3.4.2.3.
version-
-type: metadata
+- -
type: metadata
default value:
+not set- -
default value:
not setVersion of the book
+Version of the book
- -
+
date3.4.2.4.
date-
-type: metadata
+- -
type: metadata
default value:
+not set- -
default value:
not setDate the book was revised
+Date the book was revised
Output options
--
-- -
+
output3.4.3. Output options
+3.4.3.1.
output-
-type: list of strings
+- -
type: list of strings
default value:
+not set- -
default value:
not setSpecify a list of output formats to render
+Specify a list of output formats to render
- -
+
output.epub3.4.3.2.
output.epub-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for EPUB rendering
+Output file name for EPUB rendering
- -
+
output.html3.4.3.3.
output.html-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for HTML rendering
+Output file name for HTML rendering
- -
+
output.html.dir3.4.3.4.
output.html.dir-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput directory name for HTML rendering
+Output directory name for HTML rendering
- -
+
output.tex3.4.3.5.
output.tex-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for LaTeX rendering
+Output file name for LaTeX rendering
- -
+
output.pdf3.4.3.6.
output.pdf-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for PDF rendering
+Output file name for PDF rendering
- -
+
output.odt3.4.3.7.
output.odt-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for ODT rendering
+Output file name for ODT rendering
- -
+
output.html.if3.4.3.8.
output.html.if-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for HTML (interactive fiction) rendering
+Output file name for HTML (interactive fiction) rendering
+
output.base_path3.4.3.9.
output.base_path-
+type: path
+- -
type: path
default value:
+""- -
default value:
""- -
Directory where those output files will we written
-Directory where those output files will we written
Rendering options
+3.4.4. Rendering options
+3.4.4.1.
rendering.highlight-
-- -
-
rendering.highlight-
-type: string
+- -
type: string
default value:
+syntect- -
default value:
syntectIf/how highligh code blocks. Possible values: “syntect” (default, performed at runtime), “highlight.js” (HTML-only, uses Javascript), “none”
+If/how highligh code blocks. Possible values: “syntect” (default, performed at runtime), “highlight.js” (HTML-only, uses Javascript), “none”
- -
+
rendering.highlight.theme3.4.4.2.
rendering.highlight.theme-
-type: string
+- -
type: string
default value:
+InspiredGitHub- -
default value:
InspiredGitHubTheme for syntax highlighting (if rendering.highlight is set to ‘syntect’)
+Theme for syntax highlighting (if rendering.highlight is set to ‘syntect’)
- -
+
rendering.initials3.4.4.3.
rendering.initials-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseUse initials (‘lettrines’) for first letter of a chapter (experimental)
+Use initials (‘lettrines’) for first letter of a chapter (experimental)
- -
+
rendering.inline_toc3.4.4.4.
rendering.inline_toc-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseDisplay a table of content in the document
+Display a table of content in the document
- -
+
rendering.inline_toc.name3.4.4.5.
rendering.inline_toc.name-
-type: string
+- -
type: string
default value:
+"{{{loc_toc}}}"- -
default value:
"{{{loc_toc}}}"Name of the table of contents if it is displayed in document
+Name of the table of contents if it is displayed in document
- -
+
rendering.num_depth3.4.4.6.
rendering.num_depth-
-type: integer
+- -
type: integer
default value:
+1- -
default value:
1The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
+The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
- -
+
rendering.chapter3.4.4.7.
rendering.chapter-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setHow to call chapters
+How to call chapters
- -
+
rendering.part3.4.4.8.
rendering.part-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setHow to call parts (or ‘books’, ‘episodes’, ...
+How to call parts (or ‘books’, ‘episodes’, ...
- -
+
rendering.chapter.roman_numerals3.4.4.9.
rendering.chapter.roman_numerals-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf set to true, display chapter number with roman numerals
+If set to true, display chapter number with roman numerals
- -
+
rendering.part.roman_numerals3.4.4.10.
rendering.part.roman_numerals-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueIf set to true, display part number with roman numerals
+If set to true, display part number with roman numerals
- -
+
rendering.part.reset_counter3.4.4.11.
rendering.part.reset_counter-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueIf set to true, reset chapter number at each part
+If set to true, reset chapter number at each part
- -
+
rendering.chapter.template3.4.4.12.
rendering.chapter.template-
-type: string
+- -
type: string
default value:
+"{{{number}}}. {{{chapter_title}}}"- -
default value:
"{{{number}}}. {{{chapter_title}}}"Naming scheme of chapters, for TOC
+Naming scheme of chapters, for TOC
+
rendering.part.template3.4.4.13.
rendering.part.template-
+type: string
+- -
type: string
default value:
+"{{{number}}}. {{{part_title}}}"- -
default value:
"{{{number}}}. {{{part_title}}}"- -
Naming scheme of parts, for TOC
-Naming scheme of parts, for TOC
Special option
+3.4.5. Special option
+3.4.5.1.
import-
--
import-
+- -
type: path
-default value:
+not set- -
type: path
Import another book configuration file
+- -
default value:
not setImport another book configuration file
HTML options
+3.4.6. HTML options
+3.4.6.1.
html.icon-
-- -
-
html.icon-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setPath to an icon to be used for the HTML files(s)
+Path to an icon to be used for the HTML files(s)
- -
+
html.highlight.theme3.4.6.2.
html.highlight.theme-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setIf set, set theme for syntax highlighting for HTML output (syntect only)
+If set, set theme for syntax highlighting for HTML output (syntect only)
- -
+
html.header3.4.6.3.
html.header-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setCustom header to display at the beginning of html file(s)
+Custom header to display at the beginning of html file(s)
- -
+
html.footer3.4.6.4.
html.footer-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setCustom footer to display at the end of HTML file(s)
+Custom footer to display at the end of HTML file(s)
- -
+
html.css3.4.6.5.
html.css-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a stylesheet for HTML rendering
+Path of a stylesheet for HTML rendering
- -
+
html.css.add3.4.6.6.
html.css.add-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setSome inline CSS added to the stylesheet template
+Some inline CSS added to the stylesheet template
- -
+
html.css.colors3.4.6.7.
html.css.colors-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a stylesheet for the colors for HTML
+Path of a stylesheet for the colors for HTML
- -
+
html.js3.4.6.8.
html.js-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a javascript file
+Path of a javascript file
- -
+
html.css.print3.4.6.9.
html.css.print-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a media print stylesheet for HTML rendering
+Path of a media print stylesheet for HTML rendering
- -
+
html.highlight.js3.4.6.10.
html.highlight.js-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setSet another highlight.js version than the bundled one
+Set another highlight.js version than the bundled one
- -
+
html.highlight.css3.4.6.11.
html.highlight.css-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setSet another highlight.js CSS theme than the default one
+Set another highlight.js CSS theme than the default one
- -
+
html.side_notes3.4.6.12.
html.side_notes-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseDisplay footnotes as side notes in HTML/Epub (experimental)
+Display footnotes as side notes in HTML/Epub (experimental)
- -
+
html.escape_nb_spaces3.4.6.13.
html.escape_nb_spaces-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueReplace unicode non breaking spaces with HTML entities and CSS
+Replace unicode non breaking spaces with HTML entities and CSS
- -
+
html.chapter.template3.4.6.14.
html.chapter.template-
-type: string
+- -
type: string
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:
"<h1 id = 'link-{{{link}}}'>{{#has_number}}<span class = 'chapter-header'>{{{header}}} {{{number}}}</span>{{#has_title}}<br />{{/has_title}}{{/has_number}}{{{title}}}</h1>"Inline template for HTML chapter formatting
+Inline template for HTML chapter formatting
+
html.part.template3.4.6.15.
html.part.template-
+- -
type: string
-default value:
+"<h2 class = 'part'>{{{header}}} {{{number}}}</h2> <h1 id = 'link-{{{link}}}' class = 'part'>{{{title}}}</h1>"- -
type: string
Inline template for HTML part formatting
+- -
default value:
"<h2 class = 'part'>{{{header}}} {{{number}}}</h2> <h1 id = 'link-{{{link}}}' class = 'part'>{{{title}}}</h1>"Inline template for HTML part formatting
Standalone HTML options
+3.4.7. Standalone HTML options
+3.4.7.1.
html.standalone.template-
-- -
-
html.standalone.template-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of an HTML template for standalone HTML
+Path of an HTML template for standalone HTML
- -
+
html.standalone.one_chapter3.4.7.2.
html.standalone.one_chapter-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseDisplay only one chapter at a time (with a button to display all)
+Display only one chapter at a time (with a button to display all)
- -
+
html.standalone.js3.4.7.3.
html.standalone.js-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a javascript file
+Path of a javascript file
Multifile HTML options
--
-+
html.dir.template3.4.8. Multifile HTML options
+3.4.8.1.
html.dir.template-
+- -
type: template path
-default value:
+not set- -
type: template path
Path of a HTML template for multifile HTML
+- -
default value:
not setPath of a HTML template for multifile HTML
Interactive fiction HTML options
--
-- -
+
html.if.js3.4.9. Interactive fiction HTML options
+3.4.9.1.
html.if.js-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a javascript file
+Path of a javascript file
- -
+
html.if.new_turn3.4.9.2.
html.if.new_turn-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setJavascript code that will be run at the beginning of each segment
+Javascript code that will be run at the beginning of each segment
- -
+
html.if.end_turn3.4.9.3.
html.if.end_turn-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setJavascript code that will be run at the end of each segment
+Javascript code that will be run at the end of each segment
+
html.if.new_game3.4.9.4.
html.if.new_game-
+- -
type: template path
-default value:
+not set- -
type: template path
Javascript code that will be run at the beginning of a ‘game’
+- -
default value:
not setJavascript code that will be run at the beginning of a ‘game’
EPUB options
--
-- -
+
epub.version3.4.10. EPUB options
+3.4.10.1.
epub.version-
-type: integer
+- -
type: integer
default value:
+2- -
default value:
2EPUB version to generate (2 or 3)
+EPUB version to generate (2 or 3)
- -
+
epub.highlight.theme3.4.10.2.
epub.highlight.theme-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setIf set, set theme for syntax highlighting for EPUB output (syntect only)
+If set, set theme for syntax highlighting for EPUB output (syntect only)
- -
+
epub.css3.4.10.3.
epub.css-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a stylesheet for EPUB
+Path of a stylesheet for EPUB
- -
+
epub.css.add3.4.10.4.
epub.css.add-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setInline CSS added to the EPUB stylesheet template
+Inline CSS added to the EPUB stylesheet template
- -
+
epub.chapter.xhtml3.4.10.5.
epub.chapter.xhtml-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of an xhtml template for each chapter
+Path of an xhtml template for each chapter
- -
+
epub.toc.extras3.4.10.6.
epub.toc.extras-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueAdd ‘Title’ and (if set) ‘Cover’ in the EPUB table of contents
+Add ‘Title’ and (if set) ‘Cover’ in the EPUB table of contents
+
epub.escape_nb_spaces3.4.10.7.
epub.escape_nb_spaces-
+type: boolean
+- -
type: boolean
default value:
+true- -
default value:
true- -
Replace unicode non breaking spaces with HTML entities and CSS
-Replace unicode non breaking spaces with HTML entities and CSS
LaTeX options
+3.4.11. LaTeX options
+3.4.11.1.
tex.highlight.theme-
-- -
-
tex.highlight.theme-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setIf set, set theme for syntax highlighting for LaTeX/PDF output (syntect only)
+If set, set theme for syntax highlighting for LaTeX/PDF output (syntect only)
- -
+
tex.links_as_footnotes3.4.11.2.
tex.links_as_footnotes-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueAdd foontotes to URL of links so they are readable when printed
+Add foontotes to URL of links so they are readable when printed
- -
+
tex.command3.4.11.3.
tex.command-
-type: string
+- -
type: string
default value:
+xelatex- -
default value:
xelatexLaTeX command to use for generating PDF
+LaTeX command to use for generating PDF
- -
+
tex.template3.4.11.4.
tex.template-
-type: template path
+- -
type: template path
default value:
+not set- -
default value:
not setPath of a LaTeX template file
+Path of a LaTeX template file
- -
+
tex.template.add3.4.11.5.
tex.template.add-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setInline code added in the LaTeX template
+Inline code added in the LaTeX template
- -
+
tex.class3.4.11.6.
tex.class-
-type: string
+- -
type: string
default value:
+book- -
default value:
bookLaTeX class to use
+LaTeX class to use
- -
+
tex.paper.size3.4.11.7.
tex.paper.size-
-type: string
+- -
type: string
default value:
+a5paper- -
default value:
a5paperSpecifies the size of the page.
+Specifies the size of the page.
- -
+
tex.margin.left3.4.11.8.
tex.margin.left-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setSpecifies 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)
+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)
- -
+
tex.margin.right3.4.11.9.
tex.margin.right-
-type: string
+- -
type: string
default value:
+not set- -
default value:
not setSpecifies 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)
+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)
- -
+
tex.margin.top3.4.11.10.
tex.margin.top-
-type: string
+- -
type: string
default value:
+"2cm"- -
default value:
"2cm"Specifies top margin
+Specifies top margin
- -
+
tex.margin.bottom3.4.11.11.
tex.margin.bottom-
-type: string
+- -
type: string
default value:
+"1.5cm"- -
default value:
"1.5cm"Specifies left margin
+Specifies left margin
- -
+
tex.title3.4.11.12.
tex.title-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueIf true, generate a title with \maketitle
+If true, generate a title with \maketitle
- -
+
tex.font.size3.4.11.13.
tex.font.size-
-type: integer
+- -
type: integer
default value:
+not set- -
default value:
not setSpecify latex font size (in pt, 10 (default), 11, or 12 are accepted)
+Specify latex font size (in pt, 10 (default), 11, or 12 are accepted)
- -
+
tex.hyperref3.4.11.14.
tex.hyperref-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueIf disabled, don’t try to find references inside the document
+If disabled, don’t try to find references inside the document
+
tex.stdpage3.4.11.15.
tex.stdpage-
+- -
type: boolean
-default value:
+false- -
type: boolean
If set to true, use ‘stdpage’ package to format a manuscript according to standards
+- -
default value:
falseIf set to true, use ‘stdpage’ package to format a manuscript according to standards
Resources option
+3.4.12. Resources option
+3.4.12.1.
resources.files-
-- -
-
resources.files-
-type: list of strings
+- -
type: list of strings
default value:
+not set- -
default value:
not setWhitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
+Whitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
- -
+
resources.out_path3.4.12.2.
resources.out_path-
-type: path
+- -
type: path
default value:
+data- -
default value:
dataPaths where additional resources should be copied in the EPUB file or HTML directory
+Paths where additional resources should be copied in the EPUB file or HTML directory
- -
+
resources.base_path3.4.12.3.
resources.base_path-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setPath 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.
+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.links3.4.12.4.
resources.base_path.links-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setSet base path but only for links. Useless if resources.base_path is set
+Set base path but only for links. Useless if resources.base_path is set
- -
+
resources.base_path.images3.4.12.5.
resources.base_path.images-
-type: path
+- -
type: path
default value:
+.- -
default value:
.Set base path but only for images. Useless if resources.base_path is set
+Set base path but only for images. Useless if resources.base_path is set
- -
+
resources.base_path.files3.4.12.6.
resources.base_path.files-
-type: path
+- -
type: path
default value:
+.- -
default value:
.Set base path but only for additional files. Useless if resources.base_path is set.
+Set base path but only for additional files. Useless if resources.base_path is set.
- -
+
resources.base_path.templates3.4.12.7.
resources.base_path.templates-
-type: path
+- -
type: path
default value:
+.- -
default value:
.Set base path but only for templates files. Useless if resources.base_path is set
+Set base path but only for templates files. Useless if resources.base_path is set
Input options
--
-- -
+
input.clean3.4.13. Input options
+3.4.13.1.
input.clean-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueToggle typographic cleaning of input markdown according to lang
+Toggle typographic cleaning of input markdown according to lang
- -
+
input.clean.smart_quotes3.4.13.2.
input.clean.smart_quotes-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueIf enabled, tries to replace vertical quotations marks to curly ones
+If enabled, tries to replace vertical quotations marks to curly ones
- -
+
input.clean.ligature.dashes3.4.13.3.
input.clean.ligature.dashes-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf enabled, replaces ‘--’ to en dash ('–') and ‘---’ to em dash ('—')
+If enabled, replaces ‘--’ to en dash ('–') and ‘---’ to em dash ('—')
- -
+
input.clean.ligature.guillemets3.4.13.4.
input.clean.ligature.guillemets-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf enabled, replaces ‘<<’ and ‘>>’ to french “guillemets” ('«’ and ‘»’)
+If enabled, replaces ‘<<’ and ‘>>’ to french “guillemets” ('«’ and ‘»’)
- -
+
input.yaml_blocks3.4.13.5.
input.yaml_blocks-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseEnable inline YAML blocks to override options set in config file
+Enable inline YAML blocks to override options set in config file
Crowbook options
--
-- -
+
crowbook.html_as_text3.4.14. Crowbook options
+3.4.14.1.
crowbook.html_as_text-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueConsider HTML blocks as text. This avoids having
+<foo>being considered as HTML and thus ignored.Consider HTML blocks as text. This avoids having
<foo>being considered as HTML and thus ignored.- -
+
crowbook.markdown.superscript3.4.14.2.
crowbook.markdown.superscript-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf enabled, allow support for superscript and subscript using respectively fooup and bar
+downsyntax.If enabled, allow support for superscript and subscript using respectively fooup and bar
downsyntax.- -
+
crowbook.temp_dir3.4.14.3.
crowbook.temp_dir-
-type: path
+- -
type: path
default value: ``
+- -
default value:
(empty string)Path where to create a temporary directory (default: uses result from Rust’s std::env::temp_dir())
+Path where to create a temporary directory (default: uses result from Rust’s std::env::temp_dir())
- -
+
crowbook.zip.command3.4.14.4.
crowbook.zip.command-
-type: string
+- -
type: string
default value:
+zip- -
default value:
zipCommand to use to zip files (for EPUB/ODT)
+Command to use to zip files (for EPUB/ODT)
Output options (for proofreading)
--
-- -
+
output.proofread.html3.4.15. Output options (for proofreading)
+3.4.15.1.
output.proofread.html-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput file name for HTML rendering with proofread features
+Output file name for HTML rendering with proofread features
- -
+
output.proofread.html.dir3.4.15.2.
output.proofread.html.dir-
-type: path
+- -
type: path
default value:
+not set- -
default value:
not setOutput directory name for HTML rendering with proofread features
+Output directory name for HTML rendering with proofread features
+
output.proofread.pdf3.4.15.3.
output.proofread.pdf-
+- -
type: path
-default value:
+not set- -
type: path
Output file name for PDF rendering with proofread features
+- -
default value:
not setOutput file name for PDF rendering with proofread features
Proofreading options (only for output.proofread.* targets)
+3.4.16. Proofreading options (only for
+output.proofread.*targets)3.4.16.1.
proofread-
-- -
-
proofread-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf set to false, will disactivate proofreading even if one of output.proofread.x is present
+If set to false, will disactivate proofreading even if one of output.proofread.x is present
- -
+
proofread.languagetool3.4.16.2.
proofread.languagetool-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf true, try to use language tool server to grammar check the book
+If true, try to use language tool server to grammar check the book
- -
+
proofread.languagetool.port3.4.16.3.
proofread.languagetool.port-
-type: integer
+- -
type: integer
default value:
+8081- -
default value:
8081Port to connect to languagetool-server
+Port to connect to languagetool-server
- -
+
proofread.grammalecte3.4.16.4.
proofread.grammalecte-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf true, try to use grammalecte server to grammar check the book
+If true, try to use grammalecte server to grammar check the book
- -
+
proofread.grammalecte.port3.4.16.5.
proofread.grammalecte.port-
-type: integer
+- -
type: integer
default value:
+8080- -
default value:
8080Port to connect to grammalecte server
+Port to connect to grammalecte server
- -
+
proofread.repetitions3.4.16.6.
proofread.repetitions-
-type: boolean
+- -
type: boolean
default value:
+false- -
default value:
falseIf set to true, use Caribon to detect repetitions
+If set to true, use Caribon to detect repetitions
- -
+
proofread.repetitions.max_distance3.4.16.7.
proofread.repetitions.max_distance-
-type: integer
+- -
type: integer
default value:
+25- -
default value:
25Max distance between two occurences so it is considered a repetition
+Max distance between two occurences so it is considered a repetition
- -
+
proofread.repetitions.fuzzy3.4.16.8.
proofread.repetitions.fuzzy-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueEnable fuzzy string matching
+Enable fuzzy string matching
- -
+
proofread.repetitions.fuzzy.threshold3.4.16.9.
proofread.repetitions.fuzzy.threshold-
-type: float
+- -
type: float
default value:
+0.2- -
default value:
0.2Max threshold of differences to consider two strings a repetition
+Max threshold of differences to consider two strings a repetition
- -
+
proofread.repetitions.ignore_proper3.4.16.10.
proofread.repetitions.ignore_proper-
-type: boolean
+- -
type: boolean
default value:
+true- -
default value:
trueIgnore proper nouns for repetitions
+Ignore proper nouns for repetitions
- -
+
proofread.repetitions.threshold3.4.16.11.
proofread.repetitions.threshold-
-type: float
+- -
type: float
default value:
+2.0- -
default value:
2.0Threshold to detect a repetition
+Threshold to detect a repetition
Note that these options have a type, which in most case should be pretty straightforward (a boolean can be
trueorfalse, 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). Thepathtype might puzzle you a bit, but it’s equivalent to a string, except Crowbook will consider it relatively to the book file. Thetemplate pathtype is just thepathof 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
Crowbook doesn’t currently support specifying column alignment.
+-Crowbook doesn’t currently support specifying column alignment.
4.2. Footnotes
-Footnotes can be specified the following way:
-Footnotes can be useful[^1] and make you look clever. +4.2. Footnotes
+Footnotes can be specified the following way:
+Footnotes can be useful[^1] and make you look clever. [^1]: But you shouldn't use them too much. -Will be rendered as:
-Footnotes can be useful[^1] and make you look clever.
+Will be rendered as:
+-Footnotes can be useful[^1] and make you look clever.
You can use multiple paragraphs in a footnote definition. This can sometimes be useful, but it can also be tricky, as if you only let an empty line before the next paragraph, it will also be included in the footnote. And probably the next one and the following one too:
+You can use multiple paragraphs in a footnote definition. This can sometimes be useful, but it can also be tricky, as if you only let an empty line before the next paragraph, it will also be included in the footnote. And probably the next one and the following one too:
This is a footnote usage[^1]. [^1]: This is obviously part of the footnote definition. @@ -2453,45 +3012,45 @@4.2. Footnotes
This is NOT part of the foonote. -Due to its own quirks, Crowbook will duplicate footnotes if you reference them multiple times:
+Due to its own quirks,
crowbookwill duplicate footnotes if you reference them multiple times:This footnote is unique[^2] but referenced twice[^2]. [^2]: Or is it? -This footnote is unique[^2] but referenced twice[^2].
+-This footnote is unique[^2] but referenced twice[^2].
4.3. Superscript and subscript
-Crowbook
-0.12.0added experimental support for superscript and subscript, using respectivelyfoo^up^andbar~down~syntax, which will render as “fooup" and “bardown“; this feature is quite a hack above the Markdown parsing library, and as such might cause issue if you mix it with other Markdown syntax elements (or, in the previous example, for smart quote detection). This is why you’ll need to enable it withcrowbook.mardown.superscript.4.4. “Standalone” images
-This is not per se a new syntactic element, but Crowbook distinguish two kind of images, according to their position in the document:
+4.3. Superscript and subscript
+Crowbook
+v0.12.0added experimental support for superscript and subscript, using respectivelyfoo^up^andbar~down~syntax, which will render as “fooup" and “bardown“; this feature is quite a hack above the Markdown parsing library, and as such might cause issue if you mix it with other Markdown syntax elements (or, in the previous example, for smart quote detection). This is why you’ll need to enable it withcrowbook.mardown.superscript.4.4. “Standalone” images
+This is not per se a new syntactic element, but Crowbook distinguish two kind of images, according to their position in the document:
-
-standalone images, which are the only elements of a paragraph;
+- -
standalone images, which are the only elements of a paragraph;
inline images, which are placed in a container containing other elements.
+inline images, which are placed in a container containing other elements.
Standalone images will typically be resized to fill the width of the page, while inline images are not resized.
-This image is on its own paragraph, and thus considered “standalone” and resized to fit width:
+Standalone images will typically be resized to fill the width of the page, while inline images are not resized.
+This image is on its own paragraph, and thus considered “standalone” and resized to fit width:
-
While this one
-4.5. Interactive fiction
-Crowbook also adds some syntax for interactive fiction, to make embedding Javascript code easier. It is only enabled for the interactive fiction renderer. For more information, see the chapter on this matter.
+
While this one is embedded in a paragraph and its size is unchanged.
4.5. Interactive fiction
+crowbook also adds some syntax for interactive fiction, to make embedding Javascript code easier. It is only enabled for the interactive fiction renderer. For more information, see the chapter on this matter.
Chapter 5
Templates
Crowbook allows the user to specify a number of templates.[^1]
-Each of this template can be overriden by a custom one, by setting e.g.:
+Chapter 5
Templates
Crowbook allows the user to specify a number of templates.[^1]
+Each of this template can be overriden by a custom one, by setting e.g.:
html.css: my_template.css -
in the book configuration file. The templates that you are most susceptible to modify are the following:
+in the book configuration file. The templates that you are most susceptible to modify are the following:
-
-
+html.css: stylesheet for HTML output;html.css: stylesheet for HTML output;
-
+epub.css: stylesheet for EPUB output;epub.css: stylesheet for EPUB output;
-
+tex.template: template of a LaTeX file.tex.template: template of a LaTeX file.
5.1. Create and edit template
-Except for inline templates, which are set directly in the book configuration file:
+5.1. Create and edit template
+Except for inline templates, which are set directly in the book configuration file:
# Template that modify how a chapter title is displayed rendering.chapter.template: "{{{loc_chapter}}} {{{number}}}: {{{chapter_title}}}" @@ -2501,26 +3060,26 @@5.1. Create and edit template
# LaTeX code added to default LaTeX template (but doesn't override it) template.tex.add: "\usepackage{libertineotf}" -
most templates must be in a separate file:
+most templates must be in a separate file:
tex.template: my_template.tex -
--print-template
-The easiest way to create a new template is to start with the default one. In order to do so, you can use the --print-template argument:
5.1.1. --print-template
+The easiest way to create a new template is to start with the default one. In order to do so, you can use the --print-template argument:
$ crowbook --print-template tex.template > my_template.tex -
In order to get the chapter.xhtml template for EPUB3, you’ll also have to use --set epub.version 3:
In order to get the chapter.xhtml template for EPUB3, you’ll also have to use --set epub.version 3:
$ crowbook --print-template epub.chapter.xhtml --set epub.version 3 > my_epub3_template.xhtml -
Mustache syntax
-Crowbook uses rust-mustache as its templating engine, which allows to use Mustache syntax in the templates.
-It mainly boils down to using {{{foo}}}[^2] to insert the value of variable foo in the document:
5.1.2. Mustache syntax
+Crowbook uses rust-mustache as its templating engine, which allows to use Mustache syntax in the templates.
+It mainly boils down to using {{{foo}}}[^2] to insert the value of variable foo in the document:
<h1 class = "title" >{{{title}}}<h1> <h2 class = "author">{{{author}}}</h2> -
Mustache also provides the possibility of checking whether a variable is set:
+Mustache also provides the possibility of checking whether a variable is set:
{{#foo}}
Foo exists
{{/foo}}
{{^foo}}
Foo does not exist
{{^foo}}
-Crowbook uses this and sets some variables to true to allow templates to conditionally include some portions. E.g., in html.css:
Crowbook uses this and sets some variables to true to allow templates to conditionally include some portions. E.g., in html.css:
{{#lang_fr}} /* Make list displays '–' instead of bullets */ ul li { @@ -2528,91 +3087,91 @@5.1. Create and edit template
padding-left: .5em; } {{/lang_fr}} -
In this case, Crowbook sets a variable whose name is equal to lang_foo to true, allowing to have different styles for some elements according to the language.
For more information about Mustache syntax, see the Mustache manual.
-Syntax in LaTeX
-Since LaTeX already uses a lot of curly brackets, the default template sets an altenative syntax to access variables, with <<&foo>>[^3]:
In this case, Crowbook sets a variable whose name is equal to lang_foo to true, allowing to have different styles for some elements according to the language.
For more information about Mustache syntax, see the Mustache manual.
+5.1.2.1. Syntax in LaTeX
+Since LaTeX already uses a lot of curly brackets, the default template sets an altenative syntax to access variables, with <<&foo>>[^3]:
\title{<<&title>>} \author{<<&author>>} <<#has_date>>\date{<<&date>>}<</has_date>
-
-
escaping is already done by Crowbook before setting variable content;
+escaping is already done by Crowbook before setting variable content;
-escaping HTML in a LaTeX document won’t probably look good.
+escaping HTML in a LaTeX document won’t probably look good.
5.2. List of templates
-html.js
-The javascript file used by both the standalone HTML renderer and the multiple files HTML renderer.
-This is not currently an actual template, just a plain javascript file which cannot contain mustache tags.
html.css
-The main CSS file used by both the standalone HTML renderer and the multiple files HTML renderer.
-html.css.colors
-A CSS file containing only colour settings. Used by html.css.
This is not currently an actual template, just a plain CSS file which cannot contain mustache tags.
html.css.print
-An additional CSS file used by both the standalone HTML renderer and the multiple files HTML renderer. Its purpose is to provide CSS instructions for printing (i.e., when the user clicks the print button in her browser).
This is not currently an actual template, just a plain CSS file which cannot contain mustache tags.
html.highlight.js
-A javascript file used by both HTML renderers to highlight codes in code blocks. It should be a variant of highlight.js.
-This is not an actual template, just a plain javascript file.
-html.highlight.css
-A CSS file used by both HTML renderers to set the theme of highlight.js. It should, though, be an highlight.js theme.
This is not an actual template, just a plain CSS file.
-html.standalone.js
-A javascript file used only by the standalone HTML renderer. Its main purpose is to handle the displaying of a single chapter at a time when one_chapter is set to true.
html.standalone.template
-The main HTML template for standalone HTML renderer.
-html.dir.template
-The main HTML template for multiple files HTML renderer.
-tex.template
-The main (and currently only) template used by the LaTeX renderer.
-epub.chapter.xhtml
-This template is the main template used by the Epub renderer. It contains the XHTML template that will be used for each chapter.
-epub.css
-This template is used by the Epub renderer and contains the style sheet.
-Inline templates
-Crowbook also has some inline templates, that are set in the book configuration file:
+5.2. List of templates
+5.2.1. html.js
+The javascript file used by both the standalone HTML renderer and the multiple files HTML renderer.
+This is not currently an actual template, just a plain javascript file which cannot contain mustache tags.
5.2.2. html.css
+The main CSS file used by both the standalone HTML renderer and the multiple files HTML renderer.
+5.2.3. html.css.colors
+A CSS file containing only colour settings. Used by html.css.
This is not currently an actual template, just a plain CSS file which cannot contain mustache tags.
5.2.4. html.css.print
+An additional CSS file used by both the standalone HTML renderer and the multiple files HTML renderer. Its purpose is to provide CSS instructions for printing (i.e., when the user clicks the print button in her browser).
This is not currently an actual template, just a plain CSS file which cannot contain mustache tags.
5.2.5. html.highlight.js
+A javascript file used by both HTML renderers to highlight codes in code blocks. It should be a variant of highlight.js.
+This is not an actual template, just a plain javascript file.
+5.2.6. html.highlight.css
+A CSS file used by both HTML renderers to set the theme of highlight.js. It should, though, be an highlight.js theme.
This is not an actual template, just a plain CSS file.
+5.2.7. html.standalone.js
+A javascript file used only by the standalone HTML renderer. Its main purpose is to handle the displaying of a single chapter at a time when one_chapter is set to true.
5.2.8. html.standalone.template
+The main HTML template for standalone HTML renderer.
+5.2.9. html.dir.template
+The main HTML template for multiple files HTML renderer.
+5.2.10. tex.template
+The main (and currently only) template used by the LaTeX renderer.
+5.2.11. epub.chapter.xhtml
+This template is the main template used by the Epub renderer. It contains the XHTML template that will be used for each chapter.
+5.2.12. epub.css
+This template is used by the Epub renderer and contains the style sheet.
+5.2.13. Inline templates
+Crowbook also has some inline templates, that are set in the book configuration file:
-
-
+tex.template.add,html.css.addandepub.css.addallow to specify some LaTeX or CSS code directly in the book configuration file. This code will be added respectively totex.template,html.cssorepub.csstemplate. For CSS templates, this code is inserted at the end of the template (allowing to redefine rules that are set by the template); for the LaTeX template, the code is inserted at the end of the preambule, just before the\begin{document}tag, allowing to redefine commands.tex.template.add,html.css.addandepub.css.addallow to specify some LaTeX or CSS code directly in the book configuration file. This code will be added respectively totex.template,html.cssorepub.csstemplate. For CSS templates, this code is inserted at the end of the template (allowing to redefine rules that are set by the template); for the LaTeX template, the code is inserted at the end of the preambule, just before the\begin{document}tag, allowing to redefine commands.
-
+rendering.inline_toc.namesets the name of the inline table of content, if it is displayed. By default, is is set to{{{loc_toc}}}, that is, a localised version of “Table of Contents”.rendering.inline_toc.namesets the name of the inline table of content, if it is displayed. By default, is is set to{{{loc_toc}}}, that is, a localised version of “Table of Contents”.
-
+rendering.chapter.templatesets the naming scheme for chapters, whilerendering.part.templatedoes the same for part. These are used only for text-only output, such as in the TOC.html.chapter.templateandhtml.part.templateallow to change the HTML formatting for parts and chapters. These options should probably only be used if you know what you’re doing, as they can break the document. If you only need to change the name of chapters or parts, userendering.partandrendering.chapterinstead.rendering.chapter.templatesets the naming scheme for chapters, whilerendering.part.templatedoes the same for part. These are used only for text-only output, such as in the TOC.html.chapter.templateandhtml.part.templateallow to change the HTML formatting for parts and chapters. These options should probably only be used if you know what you’re doing, as they can break the document. If you only need to change the name of chapters or parts, userendering.partandrendering.chapterinstead.
5.3. List of accessible variables
-Metadata
-For every template, Crowbook exports all of the metadata:
+5.3. List of accessible variables
+5.3.1. Metadata
+For every template, Crowbook exports all of the metadata:
-
-
+author;author;
-
+title;title;
-
+subtitle;subtitle;
-
+lang;lang;
-
+subject;subject;
-
+description;description;
-
+license;license;
-
+version;version;
-
+date;date;
-any option
+metadata.foodefined in the book configuration file will also be exported asmetadata_foo.any option
metadata.foodefined in the book configuration file will also be exported asmetadata_foo.
These metadata can contain Markdown, which will be rendered. E.g., setting date: "20th of **september**" will render september in bold, using <b> tag for HTML or \textbf for LaTeX. If you need to use these data in places that don’t support formatted text (e.g. in meta tags), you can use the raw content by accessing xxx_raw instead (e.g., author_raw, title_raw, ...). (Note that the content of the raw metadata is not HTML-escaped, so in this case you might want to use {{xxx_raw}} instead of {{{xxx_raw}}}.)
For each metadata foo that is set, Crowbook also inserts a has_foo bool set to true. This allows to use Mustache’s section for some logic, e.g.:
These metadata can contain Markdown, which will be rendered. E.g., setting date: "20th of **september**" will render september in bold, using <b> tag for HTML or \textbf for LaTeX. If you need to use these data in places that don’t support formatted text (e.g. in meta tags), you can use the raw content by accessing xxx_raw instead (e.g., author_raw, title_raw, ...). (Note that the content of the raw metadata is not HTML-escaped, so in this case you might want to use {{xxx_raw}} instead of {{{xxx_raw}}}.)
For each metadata foo that is set, Crowbook also inserts a has_foo bool set to true. This allows to use Mustache’s section for some logic, e.g.:
{{{title}}}
{{#has_version}}, version {{{version}}}{{/has_version}}
-will avoid rendering “, version” when version is not set.
Localisation strings
-For all templates, Crowbook also exports some localisation strings loc_foo. They currently include:
will avoid rendering “, version” when version is not set.
5.3.2. Localisation strings
+For all templates, Crowbook also exports some localisation strings loc_foo. They currently include:
Template-dependent values
-Crowbook also exports some additional fields for some templates, see below.
+5.3.3. Template-dependent values
+Crowbook also exports some additional fields for some templates, see below.