22 releases (6 breaking)
0.7.3 | Oct 3, 2024 |
---|---|
0.7.1 | Jul 22, 2024 |
0.6.2 | Mar 22, 2024 |
0.3.1 | Dec 27, 2023 |
0.1.1 | Nov 23, 2023 |
#212 in Text processing
3,464 downloads per month
155KB
3.5K
SLoC
mdbook-pandoc
A mdbook
backend that outsources most of the rendering process to pandoc
.
By relying on pandoc, many output formats are supported, although this project was mainly developed with LaTeX in mind.
See Rendered Books for samples of rendered books.
Installation
-
Install
mdbook-pandoc
:To install the latest release published to crates.io:
cargo install mdbook-pandoc
The install the latest version committed to GitHub:
cargo install --git https://github.com/max-heller/mdbook-pandoc.git mdbook-pandoc
-
Note:
mdbook-pandoc
works best with Pandoc 2.10.1 or newer. Older versions (as old as 2.8) are partially supported, but will result in degraded output.If you have an old version of Pandoc installed (in particular, Ubuntu releases before 23.04 have older-than-recommended Pandoc versions in their package repositories), consider downloading a newer version from Pandoc's installation page.
Getting Started
Instruct mdbook
to use mdbook-pandoc
by updating your book.toml
file.
The following example configures mdbook-pandoc
to generate a PDF version of the book with LaTeX (which must be installed).
To generate other output formats, see Configuration.
[book]
title = "My First Book"
+ [output.pandoc.profile.pdf]
+ output-file = "output.pdf"
+ to = "latex"
Running mdbook build
will write the rendered book to pdf/output.pdf
in mdbook-pandoc
's build directory (book/pandoc
if multiple renderers are configured; book
otherwise).
Configuration
Since mdbook-pandoc
supports many different output formats through pandoc
, it must be configured to render to one or more formats through the [output.pandoc]
table in a book's book.toml
file.
Configuration is centered around output profiles, named packages of options that mdbook-pandoc
passes to pandoc
as a defaults file to render a book in a particular format.
The output for each profile is written to a subdirectory with the same name as the profile under mdbook-pandoc
's top-level build directory (book/pandoc
if multiple renderers are configured; book
otherwise).
A subset of the available options are described below:
Note: Pandoc is run from the book's root directory (the directory containing
book.toml
). Therefore, relative paths in the configuration (e.g. values forinclude-in-header
,reference-doc
) should be written relative to the book's root directory.
[output.pandoc]
hosted-html = "https://doc.rust-lang.org/book" # URL of a HTML version of the book
[output.pandoc.code]
# Display hidden lines in code blocks (e.g., lines in Rust blocks prefixed by '#').
# See https://rust-lang.github.io/mdBook/format/mdbook.html?highlight=hidden#hiding-code-lines
show-hidden-lines = false
[output.pandoc.profile.<name>] # options to pass to Pandoc (see https://pandoc.org/MANUAL.html#defaults-files)
output-file = "output.pdf" # output file (within the profile's build directory)
to = "latex" # output format
# PDF-specific settings
pdf-engine = "pdflatex" # engine to use to produce PDF output
# `mdbook-pandoc` overrides Pandoc's defaults for the following options to better support mdBooks
from = "commonmark" # source format; extensions enabled/disabled through this option are preserved
file-scope = true # parse each file individually before combining
number-sections = true # number sections headings
standalone = true # produce output with an appropriate header and footer
table-of-contents = true # include an automatically generated table of contents
# Arbitrary other Pandoc options can be specified as they would be in a Pandoc defaults file
# (see https://pandoc.org/MANUAL.html#defaults-files) but written in TOML instead of YAML...
# For example, to pass variables (https://pandoc.org/MANUAL.html#variables):
[output.pandoc.profile.<name>.variables]
# Set the pandoc variable named 'variable-name' to 'value'
variable-name = "value"
Features
- CommonMark + extensions enabled by mdBook
- Strikethrough (e.g.
~~crossed out~~
) - Footnotes
- Tables
- Task Lists (e.g.
- [x] Complete task
) - Heading Attributes (e.g.
# Heading { #custom-heading }
)
- Strikethrough (e.g.
- Table of contents
- Take
[output.html.redirect]
into account when resolving links - Font Awesome 4 icons (e.g.
<i class="fa fa-github"></i>
) to LaTeX
Preprocessing
mdbook-pandoc
performs a brief preprocessing pass before handing off a book to pandoc:
- In order to make section numbers and the generated table of contents, if applicable, mirror the chapter hierarchy defined in
SUMMARY.md
:- Headings in nested chapters are shrunk one level per level of nesting
- All headings except for H1s are marked as unnumbered and unlisted
- Relative links within chapters are "rebased" to be relative to the source directory so a chapter
src/foo/foo.md
can link tosrc/foo/bar.md
with[bar](bar.md)
- Pandoc implements this functionality in the
rebase_relative_paths
extension, but only for native markdown links/images, somdbook-pandoc
reimplements it to allow for supporting raw HTML links/images in the future
- Pandoc implements this functionality in the
Known Issues
- Linking to a chapter does not work unless the chapter contains a heading with a non-empty identifier (either auto-generated or explicitly specified). See: https://github.com/max-heller/mdbook-pandoc/pull/100
Comparison to alternatives
Rendered books
The following table links to sample books rendered with mdbook-pandoc
.
PDFs are rendered with LaTeX (LuaTeX).
Book | Rendered |
---|---|
Cargo Book | |
mdBook Guide | |
Rustonomicon | |
Rust Book | |
Rust by Example | |
Rust Edition Guide | |
Embedded Rust Book | |
Rust Reference | |
Rust Compiler Development Guide |
Rendering to PDF
- When
mdbook-pandoc
was initially written, existingmdbook
LaTeX backends (mdbook-latex
,mdbook-tectonic
) were not mature enough to render much besides the simplest books due to hand-rolling the markdown->LaTeX conversion step.mdbook-pandoc
, on the other hand, outsources this difficult step to pandoc, inheriting its maturity and configurability. - "Print to PDF"-based backends like
mdbook-pdf
are more mature, but produce less aesthetically-pleasing PDFs. Additionally,mdbook-pdf
does not support intra-document links or generating a table of contents without using a forked version of mdbook.
Rendering to other formats
- By outsourcing most of the rendering process to pandoc,
mdbook-pandoc
in theory supports many different output formats. Most of these have not been tested, so feedback on how it performs on non-PDF formats is very welcome!
Dependencies
~16–28MB
~431K SLoC