mirror of
https://github.com/lise-henry/crowbook
synced 2024-05-10 12:46:17 +02:00
chore: update docs
This commit is contained in:
Johannes Rappen
parent
83a9d4359c
commit
0d1ea8fad1
31
guide.book
31
guide.book
|
|
@ -2,9 +2,9 @@
|
|||
author: "Élisabeth Henry"
|
||||
title: Crowbook User Guide
|
||||
description: >-
|
||||
Crowbook allows to render a book written in Markdown in various
|
||||
formats. This is some kind of manual for it, and a way to
|
||||
demonstrate and test it.
|
||||
Crowbook allows to render a book written in Markdown in various
|
||||
formats. This is some kind of manual for it, and a way to
|
||||
demonstrate and test it.
|
||||
lang: en
|
||||
cover: cover.png
|
||||
version: 0.15.0
|
||||
|
|
@ -23,7 +23,7 @@ output.html: book.html
|
|||
output.html.dir: html
|
||||
output.pdf: book.pdf
|
||||
output.odt: book.odt
|
||||
|
||||
|
||||
output.base_path: docs/book/
|
||||
output.proofread.html: book.proof.html
|
||||
output.proofread.html.dir: html_proof
|
||||
|
|
@ -38,9 +38,9 @@ proofread.repetitions: true
|
|||
proofread.languagetool: true
|
||||
|
||||
# Rendering options
|
||||
rendering.num_depth: 2
|
||||
rendering.num_depth: 4
|
||||
rendering.initials: false
|
||||
rendering.inline_toc: false
|
||||
rendering.inline_toc: true
|
||||
rendering.chapter.template: "{{{number}}}. {{{chapter_title}}}"
|
||||
rendering.chapter.roman_numerals: false
|
||||
rendering.part.reset_counter: true
|
||||
|
|
@ -70,16 +70,13 @@ epub.version: 3
|
|||
# Finally, our files.
|
||||
# Paths are relative to the directory where this file is
|
||||
+ README.md
|
||||
+ guide/arguments.md
|
||||
+ guide/config.md
|
||||
+ guide/markdown.md
|
||||
+ guide/templates.md
|
||||
+ guide/proofreading.md
|
||||
+ guide/if.md
|
||||
+ guide/misc.md
|
||||
+ guide/contribute.md
|
||||
+ guide/01_arguments.md
|
||||
+ guide/02_config.md
|
||||
+ guide/03_markdown.md
|
||||
+ guide/04_templates.md
|
||||
+ guide/05_proofreading.md
|
||||
+ guide/06_interactive_fiction.md
|
||||
+ guide/07_miscellaneous.md
|
||||
+ guide/08_contributing.md
|
||||
- ChangeLog.md
|
||||
- LICENSE.md
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Arguments
|
||||
# Arguments
|
||||
|
||||
Crowbook can take a number of arguments, generally in the form:
|
||||
|
||||
|
|
@ -8,20 +8,28 @@ 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.
|
||||
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`:
|
||||
|
||||
## `--create`
|
||||
|
||||
**Usage**: `crowbook [BOOK] --create file_1.md file_2.md ...`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook [BOOK] -c file_1.md file_2.md ...`)
|
||||
```bash
|
||||
crowbook [BOOK] --create file_1.md file_2.md ...
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
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).
|
||||
It either prints the result to `stdout` (if `BOOK` is not specified) or generates the file `BOOK` (or abort if it already exists).
|
||||
|
||||
```bash
|
||||
crowbook foo.book --create chapter_1.md chapter_2.md chapter_3.md
|
||||
|
|
@ -59,17 +67,26 @@ 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).
|
||||
|
||||
## `--single`
|
||||
|
||||
**Usage**: `crowbook --single <FILE>`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -s <FILE>`)
|
||||
```bash
|
||||
crowbook --single <FILE>
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```yaml
|
||||
|
|
@ -95,10 +112,13 @@ That is, the chapter heading (if any) won't be displayed in the output documents
|
|||
|
||||
> Note that by default, using `--single` or `-s` sets the default LaTeX class of the book to `article` instead of `book`.
|
||||
|
||||
## `--set`
|
||||
|
||||
## `--set`
|
||||
**Usage**:
|
||||
|
||||
**Usage**: `crowbook <BOOK> --set [KEY] [VALUE]...`
|
||||
```bash
|
||||
crowbook <BOOK> --set [KEY] [VALUE]...
|
||||
```
|
||||
|
||||
This argument takes a list of `KEY` `VALUE` pairs and allows setting or overriding a book configuration option.
|
||||
All valid options in the configuration files are valid as keys.
|
||||
|
|
@ -108,22 +128,35 @@ For more information, see [the configuration file](config.md).
|
|||
$ crowbook foo.book --set tex.paper.size a4paper
|
||||
```
|
||||
|
||||
will override the paper size for PDF generation.
|
||||
will override the paper size for PDF generation.
|
||||
|
||||
## `--list-options`
|
||||
|
||||
**Usage**: `crowbook --list-options`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -l`)
|
||||
```bash
|
||||
crowbook --list-options
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## `--print-template`
|
||||
|
||||
**Usage**: `crowbook --print-template <TEMPLATE>`
|
||||
**Usage**:
|
||||
|
||||
Prints the built-in template to stdout.
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
|
|
@ -135,33 +168,57 @@ $ crowbook my.book --set html.css my_style.css
|
|||
|
||||
## `--stats`
|
||||
|
||||
**Usage**: `crowbook --stats <BOOK>`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -S <BOOK>`)
|
||||
```bash
|
||||
crowbook --stats <BOOK>
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
crowbook -S <BOOK>
|
||||
```
|
||||
|
||||
Display some statistics (word and character counts) about the book.
|
||||
|
||||
## `--proofread`
|
||||
|
||||
**Usage**: `crowbook --proofread <BOOK>`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -p <BOOK>`)
|
||||
```bash
|
||||
crowbook --proofread <BOOK>
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
crowbook -p <BOOK>
|
||||
```
|
||||
|
||||
Equivalent to `--set proofread true`, enables proofreading.
|
||||
See [Proofreading](proofreading.md).
|
||||
|
||||
## `--autograph`
|
||||
|
||||
**Usage**: `crowbook --autograph <BOOK>`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -a <BOOK>`)
|
||||
```bash
|
||||
crowbook --autograph <BOOK>
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```
|
||||
```text
|
||||
$ crowbook --autograph my.book
|
||||
CROWBOOK 0.14.0
|
||||
Enter autograph:
|
||||
|
|
@ -175,15 +232,27 @@ will add the block of text that was entered to all output files.
|
|||
|
||||
## `--verbose`
|
||||
|
||||
**Usage**: `crowbook <BOOK> --verbose`
|
||||
**Usage**:
|
||||
|
||||
```bash
|
||||
crowbook <BOOK> --verbose
|
||||
```
|
||||
|
||||
If this flag is set, Crowbook will print more warnings it detects while parsing and rendering.
|
||||
|
||||
## `--to`
|
||||
|
||||
**Usage**: `crowbook <BOOK> --to [FORMAT]`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook <BOOK> -t [FORMAT]`)
|
||||
```bash
|
||||
crowbook <BOOK> --to [FORMAT]
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
crowbook <BOOK> -t [FORMAT]
|
||||
```
|
||||
|
||||
Generate only the specified format.
|
||||
`FORMAT` must be either `epub`, `pdf`, `html`, `html.dir`, `odt` or `tex`.
|
||||
|
|
@ -207,26 +276,44 @@ will generate a `foo.pdf` file.
|
|||
|
||||
## `--output`
|
||||
|
||||
**Usage**: `crowbook <BOOK> --to <FORMAT> --output <FILE> `
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -t <FORMAT> -o <FILE> <BOOK>`)
|
||||
```bash
|
||||
crowbook <BOOK> --to <FORMAT> --output <FILE>
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
crowbook -t <FORMAT> -o <FILE> <BOOK>
|
||||
```
|
||||
|
||||
Specifies an output file.
|
||||
Only valid when `--to` is used.
|
||||
|
||||
## `--lang`
|
||||
|
||||
**Usage**: `crowbook --lang <LANG>`
|
||||
**Usage**:
|
||||
|
||||
(or `crowbook -L <LANG>`)
|
||||
```bash
|
||||
crowbook --lang <LANG>
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
crowbook -L <LANG>
|
||||
```
|
||||
|
||||
Set the runtime language used by Crowbook.
|
||||
Currently, only a french translation is available.
|
||||
By default, Crowbook uses the `LANG` environment variable to determine which language to use, but this option allows to override it (e.g. for operating systems that don't use such an option, such as Windows).
|
||||
|
||||
### Example
|
||||
### Example
|
||||
|
||||
`$ crowbook --lang fr --help`
|
||||
```bash
|
||||
$ crowbook --lang fr --help
|
||||
```
|
||||
|
||||
will display Crowbook's help message in french.
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ 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:
|
||||
|
||||
```
|
||||
```text
|
||||
+ chapter_1.md
|
||||
```
|
||||
|
||||
|
|
@ -115,7 +115,7 @@ If you have more than one, it might mess with the table of contents in some case
|
|||
|
||||
Parts are included using the `@` character, followed by the same characters than for chapters:
|
||||
|
||||
```
|
||||
```text
|
||||
@+ numbered_part.md
|
||||
+ chapter_01.md
|
||||
+ chapter_02.md
|
||||
|
|
@ -128,7 +128,7 @@ Parts are included using the `@` character, followed by the same characters than
|
|||
|
||||
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:
|
||||
|
||||
```
|
||||
```text
|
||||
@ Beginning
|
||||
+ chapter_01.md
|
||||
+ chapter_02.md
|
||||
|
|
@ -143,11 +143,11 @@ 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.
|
||||
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:
|
||||
|
||||
```
|
||||
```text
|
||||
-- section.md
|
||||
--- subsection.md
|
||||
---- subsubsection.md
|
||||
|
|
@ -196,7 +196,7 @@ See
|
|||
for more information on the various way to insert multiline strings (which mostly change the way newlines will or won't be inserted).
|
||||
|
||||
A final note on the syntax:
|
||||
all options must be set *before* the first chapter inclusion (that is, a line beginning with '+', '-', 'x.' (where `x` is a number) or '!').
|
||||
all options must be set *before* the first chapter inclusion (that is, a line beginning with `+`, `-`, `x.` (where `x` is a number) or `!`).
|
||||
|
||||
### Metadata
|
||||
|
||||
|
|
@ -385,7 +385,7 @@ they are used (or at least should be) for all formats.
|
|||
* `none`:
|
||||
disable syntax highlighting.
|
||||
|
||||
If your version of Crowbook (as is the case for Windows builds) isn't built with `syntect` support, it will default to `none` if you try to use it.
|
||||
If your version of `crowbook` (as is the case for Windows builds) isn't built with `syntect` support, it will default to `none` if you try to use it.
|
||||
|
||||
* `rendering.highlight.theme`:
|
||||
only used if `rendering.highlight` is set to `syntect`, selects the theme to use for syntax highlighting.
|
||||
|
|
@ -483,7 +483,7 @@ There are also options specific to the EPUB format:
|
|||
These options allow to embed additional files for some formats (currently, only EPUB).
|
||||
This can be useful for embedding fonts.
|
||||
|
||||
#### resources.files
|
||||
#### `resources.files`
|
||||
|
||||
A list of files or directories that should be added.
|
||||
|
||||
|
|
@ -506,7 +506,7 @@ resources.files: [fonts/font1.otf, fonts/font2.otf]
|
|||
|
||||
**default**: not set
|
||||
|
||||
#### resources.out_path
|
||||
#### `resources.out_path`
|
||||
|
||||
This option determine where (in which directory), *in the resulting document*, those files will be copied.
|
||||
The default is `data`, so by default the `resources.files` in the first example above will search `font1.otf` and `font2.otf` *in the same directory than the `.book` file*, and will copy them to `data/font1.otf` and `data/font2.otf` *in the EPUB file*.
|
||||
|
|
@ -537,486 +537,686 @@ will yield the same result.
|
|||
Here is the complete list of options.
|
||||
You can always look at it by running `crowbook --list-options` or `crowbook -l`.
|
||||
|
||||
### Metadata
|
||||
|
||||
- **`author`**
|
||||
- **type**: metadata
|
||||
- **default value**: `""`
|
||||
- Author of the book
|
||||
- **`title`**
|
||||
- **type**: metadata
|
||||
- **default value**: `""`
|
||||
- Title of the book
|
||||
- **`lang`**
|
||||
- **type**: metadata
|
||||
- **default value**: `en`
|
||||
- Language of the book
|
||||
- **`subject`**
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Subject of the book (used for EPUB metadata)
|
||||
- **`description`**
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Description of the book (used for EPUB metadata)
|
||||
- **`cover`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Path to the cover of the book
|
||||
|
||||
### Additional metadata
|
||||
|
||||
- **`subtitle`**
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Subtitle of the book
|
||||
- **`license`**
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- License of the book. This information will be displayed on PDF documents
|
||||
- **`version`**
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Version of the book
|
||||
- **`date`**
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Date the book was revised
|
||||
|
||||
### Output options
|
||||
|
||||
- **`output`**
|
||||
- **type**: list of strings
|
||||
- **default value**: `not set`
|
||||
- Specify a list of output formats to render
|
||||
- **`output.epub`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for EPUB rendering
|
||||
- **`output.html`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for HTML rendering
|
||||
- **`output.html.dir`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output directory name for HTML rendering
|
||||
- **`output.tex`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for LaTeX rendering
|
||||
- **`output.pdf`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for PDF rendering
|
||||
- **`output.odt`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for ODT rendering
|
||||
- **`output.html.if`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for HTML (interactive fiction) rendering
|
||||
- **`output.base_path`**
|
||||
- **type**: path
|
||||
- **default value**: `""`
|
||||
- Directory where those output files will we written
|
||||
|
||||
### Rendering options
|
||||
|
||||
- **`rendering.highlight`**
|
||||
- **type**: string
|
||||
- **default value**: `syntect`
|
||||
- If/how highligh code blocks. Possible values: "syntect" (default, performed at runtime), "highlight.js" (HTML-only, uses Javascript), "none"
|
||||
- **`rendering.highlight.theme`**
|
||||
- **type**: string
|
||||
- **default value**: `InspiredGitHub`
|
||||
- Theme for syntax highlighting (if rendering.highlight is set to 'syntect')
|
||||
- **`rendering.initials`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Use initials ('lettrines') for first letter of a chapter (experimental)
|
||||
- **`rendering.inline_toc`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Display a table of content in the document
|
||||
- **`rendering.inline_toc.name`**
|
||||
- **type**: string
|
||||
- **default value**: `"{{{loc_toc}}}"`
|
||||
- Name of the table of contents if it is displayed in document
|
||||
- **`rendering.num_depth`**
|
||||
- **type**: integer
|
||||
- **default value**: `1`
|
||||
- The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
|
||||
- **`rendering.chapter`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- How to call chapters
|
||||
- **`rendering.part`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- How to call parts (or 'books', 'episodes', ...
|
||||
- **`rendering.chapter.roman_numerals`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to true, display chapter number with roman numerals
|
||||
- **`rendering.part.roman_numerals`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If set to true, display part number with roman numerals
|
||||
- **`rendering.part.reset_counter`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If set to true, reset chapter number at each part
|
||||
- **`rendering.chapter.template`**
|
||||
- **type**: string
|
||||
- **default value**: `"{{{number}}}. {{{chapter_title}}}"`
|
||||
- Naming scheme of chapters, for TOC
|
||||
- **`rendering.part.template`**
|
||||
- **type**: string
|
||||
- **default value**: `"{{{number}}}. {{{part_title}}}"`
|
||||
- Naming scheme of parts, for TOC
|
||||
|
||||
### Special option
|
||||
|
||||
- **`import`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Import another book configuration file
|
||||
|
||||
### HTML options
|
||||
|
||||
- **`html.icon`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Path to an icon to be used for the HTML files(s)
|
||||
- **`html.highlight.theme`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- If set, set theme for syntax highlighting for HTML output (syntect only)
|
||||
- **`html.header`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Custom header to display at the beginning of html file(s)
|
||||
- **`html.footer`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Custom footer to display at the end of HTML file(s)
|
||||
- **`html.css`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a stylesheet for HTML rendering
|
||||
- **`html.css.add`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Some inline CSS added to the stylesheet template
|
||||
- **`html.css.colors`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a stylesheet for the colors for HTML
|
||||
- **`html.js`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a javascript file
|
||||
- **`html.css.print`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a media print stylesheet for HTML rendering
|
||||
- **`html.highlight.js`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Set another highlight.js version than the bundled one
|
||||
- **`html.highlight.css`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Set another highlight.js CSS theme than the default one
|
||||
- **`html.side_notes`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Display footnotes as side notes in HTML/Epub (experimental)
|
||||
- **`html.escape_nb_spaces`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Replace unicode non breaking spaces with HTML entities and CSS
|
||||
- **`html.chapter.template`**
|
||||
- **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>"`
|
||||
- Inline template for HTML chapter formatting
|
||||
- **`html.part.template`**
|
||||
- **type**: string
|
||||
- **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
|
||||
|
||||
- **`html.standalone.template`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of an HTML template for standalone HTML
|
||||
- **`html.standalone.one_chapter`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Display only one chapter at a time (with a button to display all)
|
||||
- **`html.standalone.js`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a javascript file
|
||||
|
||||
### Multifile HTML options
|
||||
|
||||
- **`html.dir.template`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a HTML template for multifile HTML
|
||||
|
||||
### Interactive fiction HTML options
|
||||
|
||||
- **`html.if.js`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a javascript file
|
||||
- **`html.if.new_turn`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Javascript code that will be run at the beginning of each segment
|
||||
- **`html.if.end_turn`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Javascript code that will be run at the end of each segment
|
||||
- **`html.if.new_game`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Javascript code that will be run at the beginning of a 'game'
|
||||
|
||||
### EPUB options
|
||||
|
||||
- **`epub.version`**
|
||||
- **type**: integer
|
||||
- **default value**: `2`
|
||||
- EPUB version to generate (2 or 3)
|
||||
- **`epub.highlight.theme`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- If set, set theme for syntax highlighting for EPUB output (syntect only)
|
||||
- **`epub.css`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a stylesheet for EPUB
|
||||
- **`epub.css.add`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Inline CSS added to the EPUB stylesheet template
|
||||
- **`epub.chapter.xhtml`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of an xhtml template for each chapter
|
||||
- **`epub.toc.extras`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Add 'Title' and (if set) 'Cover' in the EPUB table of contents
|
||||
- **`epub.escape_nb_spaces`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Replace unicode non breaking spaces with HTML entities and CSS
|
||||
|
||||
### LaTeX options
|
||||
|
||||
- **`tex.highlight.theme`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- If set, set theme for syntax highlighting for LaTeX/PDF output (syntect only)
|
||||
- **`tex.links_as_footnotes`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Add foontotes to URL of links so they are readable when printed
|
||||
- **`tex.command`**
|
||||
- **type**: string
|
||||
- **default value**: `xelatex`
|
||||
- LaTeX command to use for generating PDF
|
||||
- **`tex.template`**
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a LaTeX template file
|
||||
- **`tex.template.add`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Inline code added in the LaTeX template
|
||||
- **`tex.class`**
|
||||
- **type**: string
|
||||
- **default value**: `book`
|
||||
- LaTeX class to use
|
||||
- **`tex.paper.size`**
|
||||
- **type**: string
|
||||
- **default value**: `a5paper`
|
||||
- Specifies the size of the page.
|
||||
- **`tex.margin.left`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- 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.right`**
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Specifies right margin(note that with book class left and right margins are reversed for odd pages, thus the default value is 2.5cm for book class and 2cm else)
|
||||
- **`tex.margin.top`**
|
||||
- **type**: string
|
||||
- **default value**: `"2cm"`
|
||||
- Specifies top margin
|
||||
- **`tex.margin.bottom`**
|
||||
- **type**: string
|
||||
- **default value**: `"1.5cm"`
|
||||
- Specifies left margin
|
||||
- **`tex.title`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If true, generate a title with \maketitle
|
||||
- **`tex.font.size`**
|
||||
- **type**: integer
|
||||
- **default value**: `not set`
|
||||
- Specify latex font size (in pt, 10 (default), 11, or 12 are accepted)
|
||||
- **`tex.hyperref`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If disabled, don't try to find references inside the document
|
||||
- **`tex.stdpage`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to true, use 'stdpage' package to format a manuscript according to standards
|
||||
|
||||
### Resources option
|
||||
|
||||
- **`resources.files`**
|
||||
- **type**: list of strings
|
||||
- **default value**: `not set`
|
||||
- Whitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
|
||||
- **`resources.out_path`**
|
||||
- **type**: path
|
||||
- **default value**: `data`
|
||||
- Paths where additional resources should be copied in the EPUB file or HTML directory
|
||||
- **`resources.base_path`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Path where to find resources (in the source tree). By default, links and images are relative to the Markdown file. If this is set, it will be to this path.
|
||||
- **`resources.base_path.links`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Set base path but only for links. Useless if resources.base_path is set
|
||||
- **`resources.base_path.images`**
|
||||
- **type**: path
|
||||
- **default value**: `.`
|
||||
- Set base path but only for images. Useless if resources.base_path is set
|
||||
- **`resources.base_path.files`**
|
||||
- **type**: path
|
||||
- **default value**: `.`
|
||||
- Set base path but only for additional files. Useless if resources.base_path is set.
|
||||
- **`resources.base_path.templates`**
|
||||
- **type**: path
|
||||
- **default value**: `.`
|
||||
- Set base path but only for templates files. Useless if resources.base_path is set
|
||||
|
||||
### Input options
|
||||
|
||||
- **`input.clean`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Toggle typographic cleaning of input markdown according to lang
|
||||
- **`input.clean.smart_quotes`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If enabled, tries to replace vertical quotations marks to curly ones
|
||||
- **`input.clean.ligature.dashes`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If enabled, replaces '--' to en dash ('–') and '---' to em dash ('—')
|
||||
- **`input.clean.ligature.guillemets`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If enabled, replaces '<<' and '>>' to french "guillemets" ('«' and '»')
|
||||
- **`input.yaml_blocks`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Enable inline YAML blocks to override options set in config file
|
||||
|
||||
### Crowbook options
|
||||
|
||||
- **`crowbook.html_as_text`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Consider HTML blocks as text. This avoids having `<foo>` being considered as HTML and thus ignored.
|
||||
- **`crowbook.markdown.superscript`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If enabled, allow support for superscript and subscript using respectively foo^up^ and bar~down~ syntax.
|
||||
- **`crowbook.temp_dir`**
|
||||
- **type**: path
|
||||
- **default value**: ``
|
||||
- Path where to create a temporary directory (default: uses result from Rust's std::env::temp_dir())
|
||||
- **`crowbook.zip.command`**
|
||||
- **type**: string
|
||||
- **default value**: `zip`
|
||||
- Command to use to zip files (for EPUB/ODT)
|
||||
|
||||
### Output options (for proofreading)
|
||||
|
||||
- **`output.proofread.html`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for HTML rendering with proofread features
|
||||
- **`output.proofread.html.dir`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output directory name for HTML rendering with proofread features
|
||||
- **`output.proofread.pdf`**
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for PDF rendering with proofread features
|
||||
|
||||
### Proofreading options (only for output.proofread.* targets)
|
||||
|
||||
- **`proofread`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to false, will disactivate proofreading even if one of output.proofread.x is present
|
||||
- **`proofread.languagetool`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If true, try to use language tool server to grammar check the book
|
||||
- **`proofread.languagetool.port`**
|
||||
- **type**: integer
|
||||
- **default value**: `8081`
|
||||
- Port to connect to languagetool-server
|
||||
- **`proofread.grammalecte`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If true, try to use grammalecte server to grammar check the book
|
||||
- **`proofread.grammalecte.port`**
|
||||
- **type**: integer
|
||||
- **default value**: `8080`
|
||||
- Port to connect to grammalecte server
|
||||
- **`proofread.repetitions`**
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to true, use Caribon to detect repetitions
|
||||
- **`proofread.repetitions.max_distance`**
|
||||
- **type**: integer
|
||||
- **default value**: `25`
|
||||
- Max distance between two occurences so it is considered a repetition
|
||||
- **`proofread.repetitions.fuzzy`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Enable fuzzy string matching
|
||||
- **`proofread.repetitions.fuzzy.threshold`**
|
||||
- **type**: float
|
||||
- **default value**: `0.2`
|
||||
- Max threshold of differences to consider two strings a repetition
|
||||
- **`proofread.repetitions.ignore_proper`**
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Ignore proper nouns for repetitions
|
||||
- **`proofread.repetitions.threshold`**
|
||||
- **type**: float
|
||||
- **default value**: `2.0`
|
||||
- Threshold to detect a repetition
|
||||
|
||||
Note that these options have a type, which in most case should be pretty straightforward (a boolean can be `true` or `false`, an integer must be composed by a number, a string is, well, any string (note that you might need to use quotes if it includes some characters that may lead the YAML parser to read it as an array, an integer or a list), and a list of strings is a list containing only strings, see
|
||||
[YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components)).
|
||||
The `path` type might puzzle you a bit, but it's equivalent to a string, except Crowbook will consider it relatively to the book file. The `template path` type is just the `path` of a template. Metadata are just strings.
|
||||
|
||||
### Metadata
|
||||
|
||||
#### `author`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `""`
|
||||
- Author of the book
|
||||
|
||||
#### `title`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `""`
|
||||
- Title of the book
|
||||
|
||||
#### `lang`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `en`
|
||||
- Language of the book
|
||||
|
||||
#### `subject`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Subject of the book (used for EPUB metadata)
|
||||
|
||||
#### `description`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Description of the book (used for EPUB metadata)
|
||||
|
||||
#### `cover`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Path to the cover of the book
|
||||
|
||||
### Additional metadata
|
||||
|
||||
#### `subtitle`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Subtitle of the book
|
||||
|
||||
#### `license`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- License of the book. This information will be displayed on PDF documents
|
||||
|
||||
#### `version`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Version of the book
|
||||
|
||||
#### `date`
|
||||
|
||||
- **type**: metadata
|
||||
- **default value**: `not set`
|
||||
- Date the book was revised
|
||||
|
||||
### Output options
|
||||
|
||||
#### `output`
|
||||
|
||||
- **type**: list of strings
|
||||
- **default value**: `not set`
|
||||
- Specify a list of output formats to render
|
||||
|
||||
#### `output.epub`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for EPUB rendering
|
||||
|
||||
#### `output.html`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for HTML rendering
|
||||
|
||||
#### `output.html.dir`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output directory name for HTML rendering
|
||||
|
||||
#### `output.tex`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for LaTeX rendering
|
||||
|
||||
#### `output.pdf`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for PDF rendering
|
||||
|
||||
#### `output.odt`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for ODT rendering
|
||||
|
||||
#### `output.html.if`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for HTML (interactive fiction) rendering
|
||||
|
||||
#### `output.base_path`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `""`
|
||||
- Directory where those output files will we written
|
||||
|
||||
### Rendering options
|
||||
|
||||
#### `rendering.highlight`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `syntect`
|
||||
- If/how highligh code blocks. Possible values: "syntect" (default, performed at runtime), "highlight.js" (HTML-only, uses Javascript), "none"
|
||||
|
||||
#### `rendering.highlight.theme`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `InspiredGitHub`
|
||||
- Theme for syntax highlighting (if rendering.highlight is set to 'syntect')
|
||||
|
||||
#### `rendering.initials`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Use initials ('lettrines') for first letter of a chapter (experimental)
|
||||
|
||||
#### `rendering.inline_toc`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Display a table of content in the document
|
||||
|
||||
#### `rendering.inline_toc.name`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `"{{{loc_toc}}}"`
|
||||
- Name of the table of contents if it is displayed in document
|
||||
|
||||
#### `rendering.num_depth`
|
||||
|
||||
- **type**: integer
|
||||
- **default value**: `1`
|
||||
- The maximum heading levels that should be numbered (0: no numbering, 1: only chapters, ..., 6: all)
|
||||
|
||||
#### `rendering.chapter`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- How to call chapters
|
||||
|
||||
#### `rendering.part`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- How to call parts (or 'books', 'episodes', ...
|
||||
|
||||
#### `rendering.chapter.roman_numerals`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to true, display chapter number with roman numerals
|
||||
|
||||
#### `rendering.part.roman_numerals`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If set to true, display part number with roman numerals
|
||||
|
||||
#### `rendering.part.reset_counter`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If set to true, reset chapter number at each part
|
||||
|
||||
#### `rendering.chapter.template`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `"{{{number}}}. {{{chapter_title}}}"`
|
||||
- Naming scheme of chapters, for TOC
|
||||
|
||||
#### `rendering.part.template`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `"{{{number}}}. {{{part_title}}}"`
|
||||
- Naming scheme of parts, for TOC
|
||||
|
||||
### Special option
|
||||
|
||||
#### `import`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Import another book configuration file
|
||||
|
||||
### HTML options
|
||||
|
||||
#### `html.icon`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Path to an icon to be used for the HTML files(s)
|
||||
|
||||
#### `html.highlight.theme`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- If set, set theme for syntax highlighting for HTML output (syntect only)
|
||||
|
||||
#### `html.header`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Custom header to display at the beginning of html file(s)
|
||||
|
||||
#### `html.footer`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Custom footer to display at the end of HTML file(s)
|
||||
|
||||
#### `html.css`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a stylesheet for HTML rendering
|
||||
|
||||
#### `html.css.add`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Some inline CSS added to the stylesheet template
|
||||
|
||||
#### `html.css.colors`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a stylesheet for the colors for HTML
|
||||
|
||||
#### `html.js`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a javascript file
|
||||
|
||||
#### `html.css.print`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a media print stylesheet for HTML rendering
|
||||
|
||||
#### `html.highlight.js`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Set another highlight.js version than the bundled one
|
||||
|
||||
#### `html.highlight.css`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Set another highlight.js CSS theme than the default one
|
||||
|
||||
#### `html.side_notes`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Display footnotes as side notes in HTML/Epub (experimental)
|
||||
|
||||
#### `html.escape_nb_spaces`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Replace unicode non breaking spaces with HTML entities and CSS
|
||||
|
||||
#### `html.chapter.template`
|
||||
|
||||
- **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>"`
|
||||
- Inline template for HTML chapter formatting
|
||||
|
||||
#### `html.part.template`
|
||||
|
||||
- **type**: string
|
||||
- **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
|
||||
|
||||
#### `html.standalone.template`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of an HTML template for standalone HTML
|
||||
|
||||
#### `html.standalone.one_chapter`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Display only one chapter at a time (with a button to display all)
|
||||
|
||||
#### `html.standalone.js`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a javascript file
|
||||
|
||||
### Multifile HTML options
|
||||
|
||||
#### `html.dir.template`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a HTML template for multifile HTML
|
||||
|
||||
### Interactive fiction HTML options
|
||||
|
||||
#### `html.if.js`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a javascript file
|
||||
|
||||
#### `html.if.new_turn`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Javascript code that will be run at the beginning of each segment
|
||||
|
||||
#### `html.if.end_turn`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Javascript code that will be run at the end of each segment
|
||||
|
||||
#### `html.if.new_game`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Javascript code that will be run at the beginning of a 'game'
|
||||
|
||||
### EPUB options
|
||||
|
||||
#### `epub.version`
|
||||
|
||||
- **type**: integer
|
||||
- **default value**: `2`
|
||||
- EPUB version to generate (2 or 3)
|
||||
|
||||
#### `epub.highlight.theme`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- If set, set theme for syntax highlighting for EPUB output (syntect only)
|
||||
|
||||
#### `epub.css`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a stylesheet for EPUB
|
||||
|
||||
#### `epub.css.add`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Inline CSS added to the EPUB stylesheet template
|
||||
|
||||
#### `epub.chapter.xhtml`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of an xhtml template for each chapter
|
||||
|
||||
#### `epub.toc.extras`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Add 'Title' and (if set) 'Cover' in the EPUB table of contents
|
||||
|
||||
#### `epub.escape_nb_spaces`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Replace unicode non breaking spaces with HTML entities and CSS
|
||||
|
||||
### LaTeX options
|
||||
|
||||
#### `tex.highlight.theme`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- If set, set theme for syntax highlighting for LaTeX/PDF output (syntect only)
|
||||
|
||||
#### `tex.links_as_footnotes`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Add foontotes to URL of links so they are readable when printed
|
||||
|
||||
#### `tex.command`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `xelatex`
|
||||
- LaTeX command to use for generating PDF
|
||||
|
||||
#### `tex.template`
|
||||
|
||||
- **type**: template path
|
||||
- **default value**: `not set`
|
||||
- Path of a LaTeX template file
|
||||
|
||||
#### `tex.template.add`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Inline code added in the LaTeX template
|
||||
|
||||
#### `tex.class`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `book`
|
||||
- LaTeX class to use
|
||||
|
||||
#### `tex.paper.size`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `a5paper`
|
||||
- Specifies the size of the page.
|
||||
|
||||
#### `tex.margin.left`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- 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.right`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `not set`
|
||||
- Specifies right margin(note that with book class left and right margins are reversed for odd pages, thus the default value is 2.5cm for book class and 2cm else)
|
||||
|
||||
#### `tex.margin.top`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `"2cm"`
|
||||
- Specifies top margin
|
||||
|
||||
#### `tex.margin.bottom`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `"1.5cm"`
|
||||
- Specifies left margin
|
||||
|
||||
#### `tex.title`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If true, generate a title with \maketitle
|
||||
|
||||
#### `tex.font.size`
|
||||
|
||||
- **type**: integer
|
||||
- **default value**: `not set`
|
||||
- Specify latex font size (in pt, 10 (default), 11, or 12 are accepted)
|
||||
|
||||
#### `tex.hyperref`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If disabled, don't try to find references inside the document
|
||||
|
||||
#### `tex.stdpage`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to true, use 'stdpage' package to format a manuscript according to standards
|
||||
|
||||
### Resources option
|
||||
|
||||
#### `resources.files`
|
||||
|
||||
- **type**: list of strings
|
||||
- **default value**: `not set`
|
||||
- Whitespace-separated list of files to embed in e.g. EPUB file; useful for including e.g. fonts
|
||||
|
||||
#### `resources.out_path`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `data`
|
||||
- Paths where additional resources should be copied in the EPUB file or HTML directory
|
||||
|
||||
#### `resources.base_path`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Path where to find resources (in the source tree). By default, links and images are relative to the Markdown file. If this is set, it will be to this path.
|
||||
|
||||
#### `resources.base_path.links`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Set base path but only for links. Useless if resources.base_path is set
|
||||
|
||||
#### `resources.base_path.images`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `.`
|
||||
- Set base path but only for images. Useless if resources.base_path is set
|
||||
|
||||
#### `resources.base_path.files`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `.`
|
||||
- Set base path but only for additional files. Useless if resources.base_path is set.
|
||||
|
||||
#### `resources.base_path.templates`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `.`
|
||||
- Set base path but only for templates files. Useless if resources.base_path is set
|
||||
|
||||
### Input options
|
||||
|
||||
#### `input.clean`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Toggle typographic cleaning of input markdown according to lang
|
||||
|
||||
#### `input.clean.smart_quotes`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- If enabled, tries to replace vertical quotations marks to curly ones
|
||||
|
||||
#### `input.clean.ligature.dashes`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If enabled, replaces '--' to en dash ('–') and '---' to em dash ('—')
|
||||
|
||||
#### `input.clean.ligature.guillemets`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If enabled, replaces '<<' and '>>' to french "guillemets" ('«' and '»')
|
||||
|
||||
#### `input.yaml_blocks`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- Enable inline YAML blocks to override options set in config file
|
||||
|
||||
### Crowbook options
|
||||
|
||||
#### `crowbook.html_as_text`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Consider HTML blocks as text. This avoids having `<foo>` being considered as HTML and thus ignored.
|
||||
|
||||
#### `crowbook.markdown.superscript`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If enabled, allow support for superscript and subscript using respectively foo^up^ and bar~down~ syntax.
|
||||
|
||||
#### `crowbook.temp_dir`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: ` ` (empty string)
|
||||
- Path where to create a temporary directory (default: uses result from Rust's std::env::temp_dir())
|
||||
|
||||
#### `crowbook.zip.command`
|
||||
|
||||
- **type**: string
|
||||
- **default value**: `zip`
|
||||
- Command to use to zip files (for EPUB/ODT)
|
||||
|
||||
### Output options (for proofreading)
|
||||
|
||||
#### `output.proofread.html`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for HTML rendering with proofread features
|
||||
|
||||
#### `output.proofread.html.dir`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output directory name for HTML rendering with proofread features
|
||||
|
||||
#### `output.proofread.pdf`
|
||||
|
||||
- **type**: path
|
||||
- **default value**: `not set`
|
||||
- Output file name for PDF rendering with proofread features
|
||||
|
||||
### Proofreading options (only for `output.proofread.*` targets)
|
||||
|
||||
#### `proofread`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to false, will disactivate proofreading even if one of output.proofread.x is present
|
||||
|
||||
#### `proofread.languagetool`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If true, try to use language tool server to grammar check the book
|
||||
|
||||
#### `proofread.languagetool.port`
|
||||
|
||||
- **type**: integer
|
||||
- **default value**: `8081`
|
||||
- Port to connect to languagetool-server
|
||||
|
||||
#### `proofread.grammalecte`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If true, try to use grammalecte server to grammar check the book
|
||||
|
||||
#### `proofread.grammalecte.port`
|
||||
|
||||
- **type**: integer
|
||||
- **default value**: `8080`
|
||||
- Port to connect to grammalecte server
|
||||
|
||||
#### `proofread.repetitions`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `false`
|
||||
- If set to true, use Caribon to detect repetitions
|
||||
|
||||
#### `proofread.repetitions.max_distance`
|
||||
|
||||
- **type**: integer
|
||||
- **default value**: `25`
|
||||
- Max distance between two occurences so it is considered a repetition
|
||||
|
||||
#### `proofread.repetitions.fuzzy`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Enable fuzzy string matching
|
||||
|
||||
#### `proofread.repetitions.fuzzy.threshold`
|
||||
|
||||
- **type**: float
|
||||
- **default value**: `0.2`
|
||||
- Max threshold of differences to consider two strings a repetition
|
||||
|
||||
#### `proofread.repetitions.ignore_proper`
|
||||
|
||||
- **type**: boolean
|
||||
- **default value**: `true`
|
||||
- Ignore proper nouns for repetitions
|
||||
|
||||
#### `proofread.repetitions.threshold`
|
||||
|
||||
- **type**: float
|
||||
- **default value**: `2.0`
|
||||
- Threshold to detect a repetition
|
||||
|
|
@ -1,16 +1,17 @@
|
|||
# Markdown format
|
||||
|
||||
Crowbook uses
|
||||
`crowbook` uses
|
||||
[pulldown-cmark](https://github.com/google/pulldown-cmark),
|
||||
which is an implementation of
|
||||
[CommonMark](http://commonmark.org/),
|
||||
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.
|
||||
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.
|
||||
|
||||
## Tables
|
||||
|
||||
Tables can be included in your Markdown file.
|
||||
|
||||
E.g.:
|
||||
|
||||
```markdown
|
||||
|
|
@ -21,7 +22,7 @@ E.g.:
|
|||
| George Martin | A Dance with Dragons |
|
||||
```
|
||||
|
||||
will render as
|
||||
will render as
|
||||
|
||||
| Author | Book |
|
||||
|--------------------|----------------------------|
|
||||
|
|
@ -29,22 +30,22 @@ will render as
|
|||
| Terry Pratchett | Hogfather |
|
||||
| George Martin | A Dance with Dragons |
|
||||
|
||||
> Crowbook doesn't currently support specifying column alignment.
|
||||
> Crowbook doesn't currently support specifying column alignment.
|
||||
|
||||
## Footnotes
|
||||
|
||||
Footnotes can be specified the following way:
|
||||
Footnotes can be specified the following way:
|
||||
|
||||
```markdown
|
||||
Footnotes can be useful[^1] and make you look clever.
|
||||
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.
|
||||
>
|
||||
> Footnotes can be useful[^1] and make you look clever.
|
||||
>
|
||||
> [^1]: But you shouldn't use them too much.
|
||||
|
||||
You can use multiple paragraphs in a footnote definition.
|
||||
|
|
@ -62,7 +63,7 @@ This is less obviously ALSO part of the footnote definition.
|
|||
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, `crowbook` will duplicate footnotes if you reference them multiple times:
|
||||
|
||||
```markdown
|
||||
This footnote is unique[^2] but referenced twice[^2].
|
||||
|
|
@ -71,15 +72,17 @@ This footnote is unique[^2] but referenced twice[^2].
|
|||
```
|
||||
|
||||
> This footnote is unique[^2] but referenced twice[^2].
|
||||
>
|
||||
>
|
||||
> [^2]: Or is it?
|
||||
|
||||
|
||||
## Superscript and subscript
|
||||
|
||||
Crowbook `0.12.0` added experimental support for superscript and subscript, using respectively `foo^up^` and `bar~down~` syntax, which will render as "foo^up^" and "bar~down~";
|
||||
Crowbook
|
||||
[`v0.12.0`](https://github.com/lise-henry/crowbook/tree/v0.12.0)
|
||||
added experimental support for superscript and subscript, using respectively `foo^up^` and `bar~down~` syntax, which will render as "foo^up^" and "bar~down~";
|
||||
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 with `crowbook.mardown.superscript`.
|
||||
This is why you'll need to enable it with `crowbook.mardown.superscript`.
|
||||
|
||||
## "Standalone" images
|
||||
|
||||
|
|
@ -88,8 +91,8 @@ This is not *per se* a new syntactic element, but Crowbook distinguish two kind
|
|||
* standalone images, which are the only elements of a paragraph;
|
||||
* 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.
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -99,6 +102,6 @@ While this one  is embedded in a paragraph and
|
|||
|
||||
## Interactive fiction
|
||||
|
||||
Crowbook also adds some syntax for interactive fiction, to make embedding Javascript code easier.
|
||||
`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](if.md).
|
||||
|
|
@ -38,7 +38,7 @@ proofread: true
|
|||
|
||||
in the book configuration file.
|
||||
|
||||
## Repetition detection
|
||||
## Repetition detection
|
||||
|
||||
Repetition detection is enabled with:
|
||||
|
||||
|
|
@ -54,7 +54,7 @@ Default are:
|
|||
|
||||
```yaml
|
||||
# The maximum distance between two identical words to
|
||||
# consider them a repetition
|
||||
# consider them a repetition
|
||||
proofread.repetitions.max_distance: 25
|
||||
# The minimal number of occurences to consider it a repetition
|
||||
proofread.repetitions.threshold: 2.0
|
||||
|
|
@ -75,7 +75,6 @@ For more information, see
|
|||
[Caribon](https://github.com/lise-henry/caribon)'s
|
||||
documentation.
|
||||
|
||||
|
||||
> Currently, repetitions are not displayed in PDF proofreading output.
|
||||
|
||||
## Grammar checking
|
||||
|
|
@ -85,7 +84,7 @@ documentation.
|
|||
Crowbook can use
|
||||
[LanguageTool](https://languagetool.org/)
|
||||
to detect grammar errors in your text.
|
||||
It is, however, a bit more complex to activate.
|
||||
It is, however, a bit more complex to activate.
|
||||
|
||||
First, you'll have to activate this feature in your book configuration file:
|
||||
|
||||
|
|
@ -115,7 +114,7 @@ You can then run Crowbook, and it will highlight grammar errors in HTML or PDF p
|
|||
### With Grammalecte
|
||||
|
||||
[Grammalecte](http://grammalecte.net/) is a grammar checker specialized for the french language.
|
||||
If the language of your book is french, you can use it in a similar fashion to languagetool:
|
||||
If the language of your book is french, you can use it in a similar fashion to languagetool:
|
||||
|
||||
```yaml
|
||||
# Activate grammalecte support
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
# Interactive fiction
|
||||
|
||||
Version `0.12.0` added experimental support for writing interactive fiction.
|
||||
Version [`v0.12.0`](https://github.com/lise-henry/crowbook/tree/v0.12.0) added experimental support for writing interactive fiction.
|
||||
|
||||
> Since this support is experimental, it means it can change at
|
||||
> anytime, and there is no guarentee that the interactive fiction you
|
||||
> write for the current version of Crowbook will work with the next
|
||||
> write for the current version of `crowbook` will work with the next
|
||||
> release, even if it isn't a major release.
|
||||
|
||||
## Basics
|
||||
|
|
@ -16,13 +16,13 @@ If you want to have a non-linear story, you can simply use Markdown links just a
|
|||
* [It might be trapped, stay away from it](stay_away.md)
|
||||
```
|
||||
|
||||
All Crowbook renderers should render this correctly, allowing the reader to "choose her adventure".
|
||||
Note, however, that you still need to include all these Markdown files in you book configuration files.
|
||||
All `crowbook` renderers should render this correctly, allowing the reader to "choose her adventure".
|
||||
Note, however, that you still need to include all these Markdown files in you book configuration files.
|
||||
|
||||
## The interactive fiction renderer
|
||||
|
||||
While the above allows you to generate correct EPUB and PDF files, it will still display all the content if the reader chooses to read your book linearly.
|
||||
While this may not be a problem, you might want to only display the part of the book that the reader is actually exploring.
|
||||
While this may not be a problem, you might want to only display the part of the book that the reader is actually exploring.
|
||||
|
||||
In order to do so, you can use the interactive fiction html renderer:
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ This output is similar to the standalone HTML output, except the option to displ
|
|||
## Using Javascript in your interactive fiction
|
||||
|
||||
While the above allows the reader to choose his own path, its interactivity is quite limited.
|
||||
With the interactive fiction renderer, it is possible to include Javascript code in your Markdown files, using a code block element:
|
||||
With the interactive fiction renderer, it is possible to include Javascript code in your Markdown files, using a code block element:
|
||||
|
||||
```markdown
|
||||
You open the chest, and you find a shiny sword. Yay!
|
||||
|
|
@ -58,7 +58,7 @@ You encounter a goblin, armed with a knife!
|
|||
> Note that *only* the interactive fiction renderer supports this way
|
||||
> of embedding Javascript code. If you try to render a document
|
||||
> containing such code blocks to EPUB, PDF, or the "normal" HTML
|
||||
> renderer, they will be displayed as regular code blocks.
|
||||
> renderer, they will be displayed as regular code blocks.
|
||||
|
||||
## Embedding Makdown in your Javascript code embedded in your Markdown
|
||||
|
||||
|
|
@ -93,8 +93,8 @@ you'll juste have to insert a named code block with the number:
|
|||
```1
|
||||
@"Only displayed at first passage"@
|
||||
```
|
||||
|
||||
```2
|
||||
|
||||
```2
|
||||
@"Only displayed at second passage"@
|
||||
```
|
||||
|
||||
|
|
@ -102,13 +102,14 @@ you'll juste have to insert a named code block with the number:
|
|||
@"Displayed at passage 3, 4 and so on.
|
||||
```
|
||||
|
||||
## Interactive fiction options
|
||||
## Interactive fiction options
|
||||
|
||||
As other renderers, there are options specific to the interactive fiction.
|
||||
|
||||
**html.if.new_game** allows you to specify the path to a Javascript that will be run at the beginning of the game.
|
||||
Since this code is not embedded in a function and is at the root (and the beginning) of the document, it is a good place to declare all the functions and the global variables you might need for your interactive fiction mechanics.
|
||||
e.g.:
|
||||
|
||||
E.g.:
|
||||
|
||||
```yaml
|
||||
html.if.new_game: some_file.js
|
||||
|
|
@ -2,7 +2,11 @@
|
|||
|
||||
## Using Crowbook with Emacs' markdown mode
|
||||
|
||||
If you use [Emacs](https://www.gnu.org/software/emacs/) as a text editor, there is a nice [Markdown mode](http://jblevins.org/projects/markdown-mode/) to edit Markdown files.
|
||||
If you use
|
||||
[Emacs](https://www.gnu.org/software/emacs/)
|
||||
as a text editor, there is a nice
|
||||
[Markdown mode](http://jblevins.org/projects/markdown-mode/)
|
||||
to edit Markdown files.
|
||||
|
||||
It is possible to use Crowbook for HTML previewing in this mode, which [requires only minimal configuration and tweaking](http://xkcd.com/1742/):
|
||||
|
||||
|
|
@ -12,9 +16,9 @@ It is possible to use Crowbook for HTML previewing in this mode, which [requires
|
|||
```
|
||||
|
||||
You can then use `markdown-preview` (or `C-c C-c p`) to run Crowbook on this file and preview it in your browser.
|
||||
Or run `markdown-live-preview-mode` to see a live preview (updated each time you save your file) in Emacs' integrated browser.
|
||||
Or run `markdown-live-preview-mode` to see a live preview (updated each time you save your file) in Emacs' integrated browser.
|
||||
|
||||
### Some explanations if it looks a bit cryptic to you
|
||||
### Some explanations if it looks a bit cryptic to you
|
||||
|
||||
We set `markdown-command` to `crowbook`, the reason for this is a bit obvious.
|
||||
The arguments we give to crowbook might be a bit less obvious:
|
||||
|
|
@ -25,7 +29,7 @@ The arguments we give to crowbook might be a bit less obvious:
|
|||
* `--to html` specifies that HTML must be generated;
|
||||
* `--output -` tells Crowbook to display the result on the stdout, even if you set `output.html` to `some_file.html`.
|
||||
|
||||
## Embedding fonts in an EPUB file
|
||||
## Embedding fonts in an EPUB file
|
||||
|
||||
In order to embed fonts in an EPUB file, you'll first have to edit the stylesheet, which you can first obtain with:
|
||||
|
||||
|
|
@ -1,22 +1,22 @@
|
|||
# Contributing
|
||||
|
||||
Crowbook is a free software, and you can contribute to it.
|
||||
`crowbook` is a free software, and you can contribute to it.
|
||||
There are some things that can be accessible even if you don't know anything about programming.
|
||||
|
||||
## Internationalization
|
||||
|
||||
Crowbook aims to support multiple languages.
|
||||
However, unfortunately, currently only english, french, and (in a more limited way) spanish are currently supported.
|
||||
`crowbook` aims to support multiple languages.
|
||||
However, unfortunately, currently only English, French, and (in a more limited way) Spanish are currently supported.
|
||||
If you want to have better support for the language you write in, there are easy things you can do:
|
||||
|
||||
* Provide a translation for the few strings that Crowbook insert into the rendered documents.
|
||||
This is really easy, as there are currently less than a dozen of them, and you just need to create a new variant of the
|
||||
[`lang/en.yaml`](https://github.com/lise-henry/crowbook/blob/master/lang/en.yaml)
|
||||
[`./lang/en.yaml`](https://github.com/lise-henry/crowbook/blob/master/lang/en.yaml)
|
||||
file.
|
||||
* Open an
|
||||
[issue](https://github.com/lise-henry/crowbook/issues)
|
||||
about the typographic rules in your language, if Crowbook doesn't cover them.
|
||||
* Provide a translation for the Crowbook program.
|
||||
about the typographic rules in your language, if `crowbook` doesn't cover them.
|
||||
* Provide a translation for the `crowbook` program.
|
||||
It requires creating a variant of the
|
||||
[`.po` file](https://github.com/lise-henry/crowbook/blob/master/lang/fr.po),
|
||||
which is a bit more work because (at this time) it's around 1,500 lines (and less a priority than the first item of this list, as this translation only affects the the command-line interface and not the rendered documents).
|
||||
Loading…
Reference in New Issue