crowbook/book_example/arguments.md

Arguments

Crowbook can takes a list of arguments:

Render a markdown book in Epub, PDF or HTML.

USAGE:
        crowbook [OPTIONS] [--] [ARGS]

OPTIONS:
        --create <FILES>...            Creates a new book with existing markdown files.
    -h, --help                         Prints help information
    -l, --list-options                 Lists all possible option
        --list-options-md              List all options, formatted in Markdow
    -o, --output <FILE>                Specifies output file.
        --print-template <TEMPLATE>    Displays the default value of a template.
    -s, --set <KEY_VALUES>             Sets a list of book options
    -t, --to <FORMAT>                  Generate specific format [values: epub, pdf, html, tex, odt]
    -V, --version                      Prints version information
    -v, --verbose                      Activate verbose mode

ARGS:
    <BOOK>    File containing the book configuration.

Command line options allow to override options defined in configuration file. E.g., even if this file specifies 'verbose: false', calling 'crowbook --verbose ' will activate verbose mode.

Note that Crowbook generates output files relatively to the directory where is:

$ crowbook foo/bar.book --to pdf --output baz.pdf

will thus generate baz.pdf in directory foo and not in current directory.

The most important option obviously , i.e. the file configuration book. It is mandatory for most options: if you don't pass it, crowbook will simply display this help message. In a normal use case this is the only argument you'll need to pass, and crowbook will generate the book in all formats specified in the configuration file.

It is, however, possible to pass more arguments to crowbook.

--create

Usage: crowbook [BOOK] --create file_1.md file_2.md ...

Creates a new book from a list of Markdown files. It will generate a book configuration file with alle file names specified as chapter. It either prints the result to stdout (if BOOK is not specified) or generate the file BOOK (or abort if it already exists).

Examples

crowbook foo.book --create  README.md ChangeLog.md LICENSE.md

will generate a file foo.book containing:

author: Your name
title: Your title
lang: en

# Uncomment and fill to generate files
# output.html: some_file.html
# output.epub: some_file.epub
# output.pdf: some_file.pdf

# Uncomment and fill to set cover image (for Epub)
# cover: some_cover.png

# List of chapters
+ README.md
+ ChangeLog.md
+ LICENSE.md

while

crowbook --create README.md ChangeLog.md LICENSE.md

will prints the same result, but to stdout (without creating a file).

When crowbook is runned with --create, it can also uses the keys/values set by --set (see below):

$ crowbook foo.book --create file1.md file2.md --set author "Pierre
Dupont" title "Mon œuvre" lang fr

will generate a foo.book file containing

author: Pierre Dupont
title: Mon œuvre
lang: fr

# List of chapters
+ file1.md
+ file2.md

--set

usage: `crowbook --set [KEY] [VALUE]...

(or crowbook <BOOK> -s [KEY] [VALUE]...

This options takes a list KEY VALUE pairs and allows to set or override a book configuration option. All valid options in the configuration files are valid as keys. For more information, see the configuration file page.

Examples

$ crowbook foo.book --set html.css style.css

will override the CSS for HTML generation (the html.css key) to style.css.

$ crowbook foo.book --set author Foo --title Bar

will override the book title to Bar and its author to Foo.

--list-options

usage: crowbook --list-options

(or crowbook -l)

Displays all the valid options to use either in a book configuration file or with --set, with a short description. There is also --list-options-md, which outputs markdown.

--print-template

usage: crowbook --print-template template

Prints to stdout the built-in template. 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.book

Note that it is possible to use this option in conjonction with --set, though it is currently only useful for EPUB template:

$ crowbook --print-template epub.template --set epub.version 2
# Returns the template for Epub 2 (default one)
$ crowbook --print-template epub.template --set epub.version 3
# Returns the template for Epub 3

--verbose

usage: crowbook <BOOK> --verbose

If this flag is set, Crowbook will print some more messages.

--to

usage: crowbook <BOOK>--to [FORMAT]

(or crowbook <BOOK> -t [FORMAT])

Generate only the specified format. FORMAT must be either epub, pdf, html, odt or tex.

If an output file for the format is not specified in the book configuration file, crowbook will fail to render PDF, ODT and Epub (whereas it will print HTML and Tex files on stdout). It is however possible to specify a file with the --output option.

Examples

crowbook --to html foo.book

will generate some HTML, and prints it either to the file specified by output.html in foo.book, or to stdout.

crowbook --to pdf --output foo.pdf foo.book

will (try to) generate a foo.pdf file,.

--output

usage: crowbook <BOOK> --to <FORMAT> --output <FILE>

(or crowbook -t <FORMAT> -o <FILE> <BOOK>)

Specifies an output file. Only valid when --to is used.

Note that Crowbook generates output files relatively to the directory where BOOK is:

$ crowbook foo/bar.book --to pdf --output baz.pdf

will thus generate baz.pdf in directory foo and not in current directory.