MDBook EPUB Backend

(Rendered Docs)

An experimental backend to mdbook which will render your document as an EPUB file, suitable for viewing on e-readers and other similar devices.

WARNING: Not yet production ready. May eat your laundry.

Note: At the moment the default stylesheet is quite bare bones, serving mainly to reset the styling used on various devices back to a known default. This default isn't overly pretty, so you may want to include your own stylesheets.

Getting Started

Before you can use the EPUB backend, you'll need to actually install it:

$ cargo install mdbook-epub

Next you need to let mdbook know to use the alternate renderer by updating your book.toml file. This is done by simply adding an empty output.epub table.

[book]
title = "mdBook Documentation"
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
author = "Mathieu David"

[output.html]
mathjax-support = true

+ [output.epub]

Now everything is set up, just run mdbook as normal and the output directory (book/epub/ by default) should now contain an extra file called mdBook Documentation.epub (substituting in whatever your book's title is).

The mdbook-epub executable can be run in "standalone" mode. This is where the backend can be used without needing to be called by mdbook, useful if you only want to render the EPUB document.

$ mdbook-epub -s ./path/to/book/dir
$ mdbook-epub --standalone ./path/to/book/dir

Configuration

Configuration is fairly bare bones at the moment.

Recognized options:

additional-css: A list of paths to CSS stylesheets to include.

use-default-css: Controls whether to include the default stylesheet.

cover-image: A path to a cover image file for the ebook.

additional-resources: A list of path to files which should be added to the EPUB, such as typefaces. They will be added with path OEBPS/<filename>.

no-section-label: In the contents list, don't prefix the chapter title with its section number.

curly-quotes: Enable converting straight quotes 'x' and "x" to ‘x’ and “x” (aka smart quotes).

footnote-backrefs: Add backreference links to footnote definitions and allow pop-up footnote behaviour. Requires epub-version = 3.

epub-version: Specifies the EPUB version to use. If omitted, the epub-builder default version is used.

• 2 — EPUB 2.0.1
• 3 — EPUB 3.0.1

[output.epub]
additional-css = ["./path/to/main.css"]
use-default-css = false
cover-image = "ebook-cover.png"
additional-resources = ["./assets/Open-Sans-Regular.ttf"]
no-section-label = true
curly-quotes = true
epub-version = 3
footnote-backrefs = true # epub-version should be = 3

Logging, seeing progress

In order to enable logging to the screen you need to set the RUST_LOG environment variable to debug or info.

On Linux and macOS this can be done in the following way:

RUST_LOG=debug  mdbook-epub

On Windows CMD you need to set it on a separate line:

set RUST_LOG=debug
mdbook-epub

Planned Features

The following features are planned (a checked box indicates it's complete). This list is by no means complete, so feature requests are most welcome!

• [x] Make a valid EPUB file with the bare chapter contents
• [x] Generate a basic TOC
• [x] Nested chapters - currently they're all inserted at the top level
• [x] Include a default CSS stylesheet (master.css)
  • [X] Actually make that stylesheet pretty enough for human consumption
• [x] Include user-defined stylesheets and themes
• [ ] Allow users to tweak the generated page by providing their own template
• [x] Ensure the generated document is viewable on the following platforms
  • [x] Amazon Kindle
  • [x] Sony PRS-T3

Contributing

This backend is still very much in the development phase and as such a large number of features are missing. If you think of something you'd like please create an issue on the issue tracker!