Books

Books

(since 3.2) --book makes one PDF of several Markdown files:

rayomd --book docs/src/SUMMARY.md manual.pdf --toc
rayomd --book docs/ manual.pdf
rayomd --book intro.md setup.md usage.md manual.pdf

The input is one of:

• a SUMMARY.md, read as mdBook and GitBook read it: its first heading is the book's title unless it names the list (mdBook's book.toml title comes first); later level-1 or level-2 headings are parts, holding the list items after them; links in paragraphs before and after the list are prefix and suffix chapters; draft entries ([Draft]()) are skipped;
• a folder: its Markdown files by name, with README.md or index.md first;
• the files given, in their order.

A file that is missing or listed twice fails with exit code 3; --embed-source is refused (exit code 2), as a book is not reversible.

(since 5.2) --export note.md out.pdf --follow-links[=N] makes a book of a note and the notes it links to, N links deep (1 to 6, default 1), breadth first, each once, at most 1,000; linked notes that do not begin with a heading get their file name as title. --backlinks ends each file of any book with "Linked from:" and links to the files that link to it. See Obsidian Notes.

What the PDF holds

• Each file begins on a new page and is a document of its own, as Pandoc's --file-scope makes it: its link definitions, footnotes (numbered from 1, after its text) and heading anchors are its own. A file of a SUMMARY.md that does not begin with a level-1 heading gets one with its title from the list.
• The book's title, and each part's, stand alone on a page (the book's not under a theme's cover page).
• The bookmarks nest the files' headings under their parts and under the files the list nests them in, six levels at most.
• A table of contents for the whole book: after the title page with --toc, else at the first [TOC] paragraph of any file.
• Links: #heading goes into the file the link is in; other.md and other.md#heading go to that file of the book (a folder to its README.md or index.md); other links stay links to the web.
• Relative images resolve from each file's folder and must lie inside the book's folder.

All other flags apply to the whole book: style, margin, --page-size, --page-numbers, --compress, --theme, --pdfa, --pdfua. In the C++ API a book is BuildBookPdf.