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.

Examples of PDF's generated with mdbook-latex include:

| Generated PDF | Generated LaTeX | Source | Online Version | | --------------------------------- | ----------------------- | ---------------------- | --------------------- | | mdbook User Guide | LaTeX | Source | HTML |

Installation

First, install the following two programs:

Rust
mdbook

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

sh cargo install mdbook-latex

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

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:

sh cargo uninstall mdbook-latex

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

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

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?

[ ] Allow SVG images (convert to PNG for LaTeX).
[ ] Compile The Rust Book and mdbook documentation without any errors or warnings (e.g. missing Unicode characters).
[ ] 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 test suites.
[ ] Add CI/CD pipeline (trust)
[ ] Add "examples" directory.
[ ] Create documentation.
[ ] Add option for alternative markdown-to-latex converter plugin.