crowbook 0.7.0

Render a Markdown book in HTML, PDF or Epub
Documentation

Crowbook

Build Status

Render a book written in markdown to HTML, Epub or PDF.

Crowbook's purpose is to allow you to automatically generate multiple outputs formats from a book written in Markdown. Its main focus is novels, and the default settings should (hopefully) generate readable books with correct typography.

Example

To see what Crowbook's output looks like, you can read (a not-necessarily up-to-date version of) the Crowbook guide (containing this README.md file and additional documentation) rendered in HTML, PDF or EPUB.

Installing

Packages

If you are on Debian GNU/Linux or Ubuntu (on a PC architecture), you can download .deb packages on the releases page.

Binaries

See the releases page to download a precompiled binary for your architecture (currently: Linux, Windows and MacOSX). Just extract the archive and run crowbook (or crowbook.exe on Windows). You might also want to copy the binary somewhere in your PATH for later usage.

Building

You'll need to have the Rust compiler on your machine first; you can download and install it here. Once it is down:

$ cargo install crowbook

will automatically download the latest crowbook release on crates.io and install it.

Usage

The simplest command is:

$ crowbook <BOOK>

where BOOK is a configuration file. Crowbook will parse this file and generate a book in HTML, Epub, LaTeX, and/or PDF, according to the settings in the configuration file.

To create a new book, assuming you have a list of Markdown files, you can generate a template configuration file with the --create argument:

$ crowbook --create my.book chapter_*.md

This will generate a default my.book file, which you'll need to complete. This configuration file contains some metadata, options, and lists the Markdown files.

For more information see the configuration file.

It is also possible to give additional parameters to crowbook; we have already seen --create, but if you want the full list, see the arguments.

Current features

Output formats

Crowbook should correctly support HTML and EPUB (either version 2 or 3) as output formats: rendered files should pass respectively the W3C validator and the IDPF EPUB validator for a wide range of (correctly Markdown formatted) input files. See the example book rendered in HTML and EPUB on github.io.

LaTeX/PDF output is a bit more tricky: it should work reasonably well for novels (the primary target of Crowbook), but pdflatex might occasionally choke on some "weird" unicode character. See the example book rendered in PDF on github.io.

ODT output is currently experimental at best. It might work with very basic formatting but still needs a lot of work. You can still see the example book rendered in ODT on github.io to have an idea of the current status for this output format.

Input format

Crowbook uses pulldown-cmark and thus should support most of CommonMark Markdown. Inline HTML, however, is not implemented, and probably won't be, as the goal is to have books that can also be generated in PDF (and maybe eventually ODT).

Maybe the most specific "feature" of Crowbook is that (by default, it can be deactivated) it tries to "clean" the input files. By default this doesn't do much (except removing superfluous spaces), but if the book's language is set to french it tries to respect french typography, replacing spaces with non-breaking ones when it is appropriate (e.g. in french you are supposed to put a non-breaking space before '?', '!', ';' or ':'). This feature is relatively limited at the moment, but I might try to add more options and support for more languages.

Links handling

Crowbook tries to correctly translate local links in the input Markdown files: e.g. if you have a link to a markdown file that is part of your book, it will be transformed into a link inside the document.

Inline YAML blocks

Crowbook supports inline YAML blocks:

---
author: Me
title: My title
---

This is mostly useful when Crowbook is runned with the --single argument (receiving a single Markdown file instead of a book configuration file). E.g., the following Markdown file:

---
author: John Doe
title: A book

output.html: book.html
---

This is a very tiny book!

can be processed with crowbook --single foo.md or crowbook -s foo.md to produce the book.html file. This is useful for short texts that typically only contain one "chapter".

Bugs

See the github's issue tracker.

Contributors

Acknowledgements

Besides the Rust compiler and standard library, Crowbook uses the following libraries:

It also uses configuration files from rust-everywhere to use Travis and Appveyor to generate binaries for various platforms on each release.

While Crowbook directly doesn't use them, there was also inspiration from Pandoc and mdBook.

Also, the W3C HTML validator and the IDPF EPUB validator proved very useful during development.

ChangeLog

See ChangeLog.

Library

While the main purpose of Crowbook is to be runned as a command line, the code is written as a library, so if you want to build on it you can use it as such. You can look at the generated documentation on docs.rs.

License

Crowbook is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License (LGPL), version 2.1 or (at your option) any ulterior version. See LICENSE for more information.