Home

Awesome

mdbook-latex

mdbook-latex logo

crates badge docs badge ci badge source badge

<!-- toc --> <!-- tocstop -->

An mdbook backend for generating LaTeX and PDF documents. Utilizes md2tex for the markdown to LaTeX transformation, but with the goal of allowing alternative markdown to LaTeX converters. If you have developed your own markdown to LaTeX converter, I'd love to talk with you or share ideas! I'm at liam@liambeckman.com.

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.

Failure: For what to do if and when mdbook-latex fails, see mdbook-latex failed to build my book! Now what? >:(. I'm also available via e-mail if you have any questions or suggestions!

Status of Rust Bookshelf

Compiles?Generated PDFGenerated LaTeXSourceOnline Version
Cargo BookLaTeXSourceHTML
Edition GuideLaTeXSourceHTML
Embedded Rust BookLaTeXSourceHTML
🍊Mdbook User GuideLaTeXSourceHTML
Rust ReferenceLaTeXSourceHTML
Rust By ExampleLaTeXSourceHTML
🍊Rust Programming LanguageLaTeXSourceHTML
Rustc BookLaTeXSourceHTML
Rustdoc BookLaTeXSourceHTML
RustonomiconLaTeXSourceHTML
Unstable BookLaTeXSourceHTML

Installation

Requirements

Cargo install + Configuration

cargo install mdbook-latex

Add the following toml configuration to book.toml.

[output.latex]
latex    = true  # default = true
pdf      = true  # default = false
markdown = true  # default = false

The next mdbook build command will produce LaTeX and PDF files (and the markdown file of your mdbook) 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
- markdown = true

Primary Dependencies

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

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 (loosely in a "top-down" direction).

See Also

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

mdbook-latex failed to build my book! Now what? >:(

Automatic Approach

Oops! That means I still have more work to do. If you absolutely need your PDF right now, then the quicket option is to select the print icon in the upper right corner of the online page of your book.

Another method is to run the markdown file through an alternative markdown to LaTeX converter like pandoc:

pandoc --from markdown --to latex book/latex/MY_BOOK.md -o book/latex/MY_BOOK.pdf

Or run it through a free (as in free parking) online solution:

Manual Approach

If, however, you don't mind getting your hands dirty with LaTeX, here is my process for when the build step fails:

  1. Change the latex configuration in book.toml to only output LaTeX and markdown files:
[output.latex]
latex = true
pdf = false
markdown = true
  1. First see where tectonic is running into errors by manually running it and looking for ! LaTeX Error:
tectonic book/latex/MY_BOOK.tex

note: this is a BETA release; ask questions and report bugs at https://tectonic.newton.cx/
Running TeX ...
error: something bad happened inside TeX; its output follows:

===============================================================================
(MY_BOOK.tex
.
.
.
! LaTeX Error: Missing \begin{document}.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...

l.260 \clearpage

No pages of output.
Transcript written on MY_BOOK.log.
===============================================================================

error: the TeX engine had an unrecoverable error
caused by: halted on potentially-recoverable error as specified

Aha! ! LaTeX Error: Missing \begin{document}.

In this example, mdbook-latex failed to output the very important \begin{document} line.

  1. Fix the grievous goof-up in your favorite editor and rerun tectonic (repeat this step until tectonic successfully compiles the PDF):
ed book/latex/MY_BOOK.tex

tectonic book/latex/MY_BOOK.tex

Is it an elegant approach? No. Does it work? Sometimes. Is it a pain? Always.

Finally

If you're feeling especially adventurous, create an issue or get in touch with me (liam@liambeckman.com) to help prevent the same errors in the future. I'm more than happy to work with you to get your document compiled!

: ^ )

Status of Binary Releases

Binary?Target
armv7-unknown-linux-gnueabihf
i686-pc-windows-gnu
i686-unknown-linux-gnu
x86_64-apple-darwin
x86_64-pc-windows-gnu
x86_64-unknown-freebsd
x86_64-unknown-linux-gnu