mdbook-tectonic

• Status of Rust Bookshelf
• Installation
• Uninstallation
• Primary Dependencies
• How's it Work?
• Contributing
  • I found a problem. Should I create an issue with mdbook-tectonic or md2tex?
• Are We Stable Yet?
  • Manual Approach
  • Finally

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.

Status of Rust Bookshelf

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

Installation

Requirements

• Rust
• mdbook
• Tectonic + support libraries

Cargo install + Configuration

cargo install mdbook-tectonic

Add the following toml configuration to book.toml.

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

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-tectonic, enter the following in a shell:

cargo uninstall mdbook-tectonic

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

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

Primary Dependencies

mdbook-tectonic 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-tectonic 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-tectonic 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-tectonic): 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-tectonic or md2tex?

Either one. mdbook-tectonic 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-tectonic 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).

• 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)
• Move all LaTeX data to single template file (src/template.tex).
• Add support for raw HTML tables.
• Add syntax highlighting via syntect à la lumpy-leandoc.
• Add parallel transformations via Rayon à la lumpy-leandoc.
• Use lumpy-leandoc's method for handling events (replace current event with fold).
• 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.
• Complete acordance with the CommonMark spec.

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

2. First see where tectonic is running into errors by manually running it and looking for ! LaTeX Error:

tectonic book/latex/MY_BOOK.tex

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

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

3. 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!

: ^ )