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.
| 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 |
sh
cargo install mdbook-tectonic
Add the following toml configuration to book.toml.
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.
To uninstall mdbook-tectonic, enter the following in a shell:
sh
cargo uninstall mdbook-tectonic
Then delete the [output.latex] configuration in book.toml:
diff
- [output.latex]
- latex = true
- pdf = true
- markdown = true
mdbook-tectonic is built upon some really wonderful projects, including:
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.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.
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.
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!
Below is a list of features I am currently working on (loosely in a "top-down" direction).
book/latex directory to keep src clean.current event with fold).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:
toml
[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:
```sh 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):
```sh 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.
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!
: ^ )