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

| Compiles? | Generated PDF | Generated LaTeX | Source | Online Version | | --------- | --------------------------------- | ----------------------- | ---------------------- | --------------------- | | ❌ | ~~Cargo Book~~ | ~~LaTeX~~ | Source | HTML | | ❌ | ~~Edition Guide~~ | ~~LaTeX~~ | Source | HTML | | ❌ | ~~Embedded Rust Book~~ | ~~LaTeX~~ | Source | HTML | | 🍊 | Mdbook User Guide | LaTeX | Source | HTML | | ❌ | ~~Rust Reference~~ | ~~LaTeX~~ | Source | HTML | | ❌ | ~~Rust By Example~~ | ~~LaTeX~~ | Source | HTML | | 🍊 | Rust Programming Language | LaTeX | Source | HTML | | ❌ | ~~Rustc Book~~ | ~~LaTeX~~ | Source | HTML | | ❌ | ~~Rustdoc Book~~ | ~~LaTeX~~ | Source | HTML | | ❌ | ~~Rustonomicon~~ | ~~LaTeX~~ | Source | HTML | | ❌ | ~~Unstable Book~~ | ~~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

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).
  • [x] 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!