mdbook-latex

An mdbook backend for generating LaTeX and PDF documents.

Warning: Not yet stable — may eat, shred, and atomize your laundry! See the Are We Stable Yet? section for a roadmap to the production release.

Status of Rust Bookshelf

• ✅ compiles successfully
• 🍊 compiles but with warnings/errors
• ❌ compilation fails/not yet attempted

Installation

First, install the following two programs:

• Rust
• mdbook

Then, to install mdbook-latex, enter the following in a shell:

cargo install mdbook-latex

Finally, add the following toml configuration to book.toml.

[output.latex]
latex = true
pdf = true

The next mdbook build command will produce LaTeX and PDF files in the book/latex/ directory.

Uninstallation

To uninstall mdbook-latex, enter the following in a shell:

cargo uninstall mdbook-latex

Then delete the [output.latex] configuration in book.toml:

- [output.latex]
- latex = true
- pdf = true

Primary Dependencies

mdbook-latex is built upon some really wonderful projects, including:

• pulldown-cmark: Parses the markdown source AST.
• Tectonic: Creates the final PDF file from the transformed LaTeX code.
• md2tex: Transforms the markdown source to LaTeX. This is a fork of md2pdf, a great utility for converting markdown code to LaTeX and PDF's. I hope to eventually propose some of the updates back upstream. md2tex and mdbook-latex are developed in tandem, but are meant to be independent programs. Therefore, if one wishes to use an alternative markdown-to-tex conveter, they should be able to plug it in to mdbook-latex with ease.

How's it Work?

Broadly speaking, there are three steps, or "transformations", from mdbook source to PDF output:

1. mdbook source to JSON-organized markdown (mdbook-latex): retreives the JSON formatted data from mdbook. Calls md2tex and tectonic for LaTeX and PDF generation, respectively.
2. markdown to LaTeX (md2tex): converts markdown input to LaTeX output.
3. LaTeX to PDF (tectonic): creates PDF document from LaTeX input.

Contributing

Pull requests, forks, and plain old copy-pasting are actively encouraged! Also, I am relatively new to Rust (and programming in general) so recommendations or advice in general is always appreciated.

I found a problem. Should I create an issue with mdbook-latex or md2tex?

Either one. mdbook-latex can be thought of as a frontend for the LaTeX generation done by md2tex. So if there is a LaTeX error, you may favor creating an issue with md2tex. Otherwise, creating an issue with mdbook-latex is a good bet. But any issue is a good issue, so don't worry if it's in the "right" repository or not, I should be able to see it regardless!

Are We Stable Yet?

Below is a list of features I am currently working on (loosly in "top-down" direction).

• Add support for equation delimiters "( x^{2 )" "[ x}2 ]".
• Allow SVG images (convert to PNG for LaTeX).
  • Configure resvg library to convert SVG's to PNG.
  • Save SVG's in book/latex directory to keep src clean.
• Add CI/CD pipeline (travis)
• Compile The Rust Book and mdbook documentation without any errors or warnings (e.g. missing Unicode characters). See Status of Rust Bookshelf for up to date progress.
• Put "tectonic" dependency in "pdf" feature configuration.
• Add "table of contents" mdbook toml option.
• Add "markdown" mdbook toml option.
• Add "number of words" mdbook toml option.
• Add "examples" directory.
• Create documentation and move relevent docs to md2tex.
• Add option for custom LaTeX headers.
• Add option for alternative markdown-to-latex converter plugin.
• Add test suites.
• Cross compile binaries (trust)
• Add option to generate PDF with mdproof to skip LaTeX dependencies.

See Also

The following projects served as guidance for mdbook-latex (or are simply cool enough that they deserve to be shared!):

• mdbook-epub: A backend for mdbook that creates EPUB files.
• mdbook-linkcheck: A backend for mdbook that will verify URL links.
• LaTeX-rs: A cool library for programmatic LaTeX generation that I hope to eventually incorporate.
• crowbook: A rich program that can generate HTML, PDF, and EPUB files from markdown code. Has a neat online demo page to try it out interactively. Similar in some respects to mdbook, but with an added focus on "novels and fiction". Though general enough to handle a lot of different projects.
• no starch press: The Rust Programming Language made professionally by a proper publishing company. Guranteed to have fewer errors than mdbook-latex!