Letterpress is a project aimed at simplifying the self-publishing process for books. It provides a ready-to-use template based on AsciiDoctor, catering to authors who need robust support for diagramming, coding examples, and mathematical formulas.

Contributing

Contributions to Letterpress are welcome! If you have suggestions, improvements, or bug fixes, please fork the repository and submit a pull request.

Tools

This Project makes use of the following tools:

Nix (flakes) for reproducible builds and dev environments
GNU Make
Asciidoctor

Batteries included

Everything you need to get started is included in the package

Nix flake: Reproducible toolchain for local dev and CI/CD
Devcontainers: Allows you to build your book locally
GitHub Workflows: Allows you to build your book on GitHub CI

Bring your own

Content
Images

Development environment

Letterpress ships a Nix flake that pins the entire toolchain (Asciidoctor, asciidoctor-pdf/epub3/diagram/mathematical, PlantUML, Mermaid, Graphviz, a JRE, Vale and EPUBCheck). This is the same environment used in CI, so builds are reproducible everywhere.

Enter the dev shell

nix develop

This drops you into a shell with every tool on PATH, so all the make commands below just work. If you use direnv, run direnv allow once and the environment loads automatically.

Build the book with Nix

You can build the book directly, without entering a shell, and get a result symlink containing book.pdf and book.epub:

nix build            # builds both PDF and EPUB into ./result
ls result/

Under the hood this runs the same make targets described below inside the pinned environment.

Commands

The make commands below assume the toolchain is available. The easiest way to get it is the Nix dev shell (nix develop); alternatively install the tools yourself.

Generate

In order to generate the PDF and the EPUB versions of the book you can just run:

make

If you just need to generate the PDF:

make output/book.pdf

If you just need to generate the EPUB:

make output/book.epub

Count

make count

Validate EPUB

Letterpress can validate the generated EPUB with EPUBCheck. EPUBCheck is provided by the Nix dev shell (or install it yourself), then run:

make epubcheck

This builds the EPUB (if needed) and then validates it.

Clean

In order to remove the generated files you can run:

make clean

Linting

Letterpress comes with vale. Vale is provided by the Nix dev shell (or install it yourself), then run:

make lint

Structure

The entry point of the book is book.adoc.

The book.adoc consists of 3 sections:

The body is where should be placing the main content of your book.