6.6 KiB
Arguments
Crowbook can takes a list of arguments:
Render a markdown book in Epub, PDF or HTML.
USAGE:
crowbook [FLAGS] [OPTIONS] [--] [ARGS]
FLAGS:
-d, --debug Print debugging information
-h, --help Prints help information
-l, --list-options Lists all possible option
--list-options-md List all options, formatted in Markdown.
-s, --single Use a single Markdown file instead of a book configuration file
-V, --version Prints version information
-v, --verbose Print warnings in parsing/rendering
OPTIONS:
--create <FILES>... Creates a new book with existing markdown files.
-o, --output <FILE> Specifies output file.
--print-template <TEMPLATE> Displays the default value of a template.
--set <KEY_VALUES> Sets a list of book options
-t, --to <FORMAT> Generate specific format [values: epub, pdf, html, tex, odt]
ARGS:
<BOOK> File containing the book configuration, or a Markdown file when called with --single.
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
--single
usage: crowbook --single <FILE>
(or crowbook -s <FILE>)
This options allows to pass 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 with --- (three dashes). E.g:
---
author: Joan Doe
title: A short story
---
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 generate a .book configuration file for a
short story or an article. crowbook --single 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).
--set
usage: `crowbook --set [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.