CLI reference

usage: fleuron <input.md…> -o <output.pdf|output.epub> [-c <style.css>]

  -o, --output <path>  where to write the book: a PDF, or a reflowable
                       EPUB when the path ends in .epub
  -c, --css <path>     author stylesheet, cascading over the defaults;
                       repeatable, applied in the order given
  -s, --split <n|none> where a markdown file's sections begin: at a
                       heading of level n or shallower, or nowhere at
                       all, one section per file (default 1)
  -d, --dialect <name> fleuron, commonmark, gfm or obsidian (default
                       fleuron: CommonMark, frontmatter and attribute
                       lines)
  --title <text>       the book's title
  --author <text>      the book's author
  --meta <key=value>   any other metadata field; repeatable. `language`
                       is the one the PDF writer reads
  --dump-tree          write the content tree the frontend read to
                       stdout as JSON, and lay nothing out
  --css-subset         write the CSS the engine accepts to stdout as
                       JSON, and read nothing
  -V, --version        print the version and exit
  -h, --help           print this message and exit

Arguments

<input.md…>	One or more markdown files, composed in the order given, each recorded in the tree under its own name. An extension that is not .md or .markdown is an error naming the file.
-o, --output	Where the book goes. A path that ends in .epub gets a reflowable EPUB, and any other path gets a PDF. See EPUB. Required, except under --dump-tree. The path is written whole and nothing is created alongside it.
-c, --css	An author stylesheet. Repeatable. Sheets parse in the order given and cascade in that order, all of them over the built-in user-agent sheet. With no -c, the built-in sheet does all the styling.
-s, --split	Where a markdown file’s sections begin. A level of 1 to 6 opens a section at every heading of that level or shallower. none opens none, so the file is one section. Default 1.
-d, --dialect	Which markdown is being read: fleuron, commonmark, gfm or obsidian. fleuron is the default: CommonMark, a frontmatter block and attribute lines. commonmark is that without the attribute lines, so a brace run is prose. See the markdown mapping.
--title, --author, --meta	The book’s own metadata. --meta takes key=value and is repeatable. The engine reads three fields in all: title and author become the PDF’s document information, and --meta language=en becomes its language and picks the hyphenation patterns.
--dump-tree	Writes the content tree the frontend read to stdout as JSON, and lays nothing out. The same manuscript dumps the same bytes every time.
--css-subset	Writes the CSS subset the engine accepts to stdout as JSON, with the engine version it came from, and reads nothing. A host pins the file for the version it embeds.
-V, --version	Prints fleuron <version> and exits 0, whether or not a job was named.
-h, --help	Prints the usage above and exits 0, whether or not a job was named.

A lone markdown input is the whole book, so its frontmatter fills whatever --title, --author and --meta leave unset. Several inputs are chapters, and each file’s frontmatter stays with the section it became.

An unrecognized option beginning with - is a usage error. There is no -- separator: every positional argument is an input, and every option takes its value next.

Exit codes

code	meaning
0	The PDF or the EPUB was written. Warnings do not change this.
1	The job was named and failed. Nothing was written.
2	The command line named no job to do.

Exit 2 means the command line is wrong. Exit 1 means the input is. A book that laid out with warnings exits 0, so a build that must fail on warnings checks stderr.

stderr

The run writes everything to stderr. stdout is only what --version, --help, --dump-tree and --css-subset print.

A summary comes first:

fleuron: manuscript.md → book.pdf: 333 pages

Then each warning, prefixed with its origin when it has one:

fleuron: warning: house.css:14:3: Unsupported property `text-shadow`. The declaration is ignored.
fleuron: warning: chapter-03.md:88:1: Unsupported attribute. Only `.class` or `#id` are valid.
fleuron: 2 warnings. The PDF was written anyway.

The origin is either a CSS sheet with a line and column, or a markdown file and the position the frontend read the node from. Diagnostics covers what warns and why.

What the PDF holds

The PDF holds the pages of the book, the fonts and images that the pages use, and the document information from --title, --author, and --meta language. It also holds links and an outline, which a reader uses on a screen.

Each link in the book is a link in the PDF. A link to a heading or an id in the book goes to the page where that element is. A link to a web address, such as https://example.com, opens that address. A link that breaks across two lines is a link on each line. The space between the lines is not part of the link. If a link names nothing in the book, its text is not a link, and the run warns.

The outline is the list of the headings of the book. A PDF viewer shows it beside the pages, and each entry goes to the page of its heading. A level 2 heading is under the level 1 heading before it. A heading in a quotation, a list, or a table is not in the outline. A book with no headings has no outline.

What the EPUB holds

If the output path ends in .epub, the EPUB holds one XHTML document for each section, and one stylesheet. It also holds the images and the fonts that the book and the stylesheets name. The table of contents is the list of the headings of the book. The metadata comes from --title, --author, and --meta. EPUB covers each part, and CSS in an EPUB covers the stylesheet.

Fonts and images on the command line

@font-face and image urls are treated as file paths. Each is tried against the directory of every manuscript and of every stylesheet given with -c, in order, and then against the working directory. The engine opens nothing itself, so this resolution belongs to the binary. A library embedding fleuron supplies its own.

An image the binary cannot open, or opens and cannot read a header from, is a warning naming the url, and the book is laid out without it.