Export Rust markdown documents in EPUB and PDF in minutes

Why you should learn Rust

Rust has topped the Stackoverflow Developer Survey as the most loved language for over seven years in a row. It has a steep learning curve and many concepts are difficult to grasp for beginners to programming, especially if you are new to systems programming and functional programming in general. But once you are over that initial hurdle, Rust enables you to spend less time dealing with bugs and race conditions and time writing more productive code.

As a data engineer with experience in dynamically typed languages such as Python, the initial complexity of Rust came as a shock personally. But fear not, if you’re just getting started and you are new to software engineering, my strongest recommendation is to start out small.

Follow simple tutorials such as Rustlings and play around with crates such as Synth for synthetic data generation (it can generate many millions of rows of data in less than 30 seconds!) or build an ORM interface for your SQL database with Diesel.

The one thing that Rust does exceptionally well, apart from speed an reliability, is it’s documentation and error handling system. Rust’s official documentation is written using the crate (Rust speak for package) Mdbook which converts markdown files to a fully fledged documentation site. And a large portion of Rust crates are referenced in this format.

Why epub?

If you spend a good portion of time in front of a screen you may find it straining to read longer documents on a computer screen. I for one use the Kobo Libra H2O E-reader for these purposes.

Convert mdbook repositories to epub

Installing Rust

First, make sure you have rust installed locally on your computer. Open a terminal and run the following command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This will run an install script to get you set up with the necessary dependencies to work with Rust. You may need to restart your terminal to be able to run commands. Try running the below to see if you have the latest version of Rust installed (1.66.1 at time of writing):

rustc --version

Converting mdbook to epub:

The crate we will use to convert to epub is called mdbook-epub.

Other crates that are useful generating PDFs are mdbook-compress or crowbook.

In this example we will use The Rust Programming Language as our mdbook target. Clone the project and cd into the directory:

git clone https://github.com/rust-lang/book.git rust_lang_book
cd rust_lang_book
# open project in VSCode
open .

Open the project in your IDE, pop open an integrated terminal and install the mdbook and mdbook-epub crates:

cargo install mdbook
cargo install mdbook-epub

Open book.toml in the root of the book’s directory and add the following line:

[book]
title = "The Rust Programming Language"
authors = ["Steve Klabnik", "Carol Nichols", "Contributions from the Rust Community"]

[output.html]
additional-css = ["ferris.css", "theme/2018-edition.css"]
additional-js = ["ferris.js"]
git-repository-url = "https://github.com/rust-lang/book"

# add the line below and save the file.
[output.epub]

To generate the epub file run the following command in the terminal:

mdbook build

Great! A new folder called /book is created in the root of the book’s directory. There you will find the epub version. Copy it over to your e-book reader and you’re good to go.

Happy reading and good luck in your Rust journey!