Contents
  1. Downloads
  2. Preface
  3. Part I Writing
  4. 1 Quickstart
  5. 2 Writing in Markdown
  6. 3 Authoring in Hiccup
  7. Part II Configuration and Theming
  8. 4 Configuring the Book
  9. 5 Theming and Editions
  10. 6 Commands
  11. Part III Producing and Publishing
  12. 7 Producing a Book
  13. Structure lives in book.edn
  14. 8 Editions
  15. 9 Distributing Your Book
  16. 10 How It Works
  17. A Error Catalog
  18. B Clojure for Authors
  19. C A Chapter Written in Code
  20. A table the book writes for itself
  21. Documentation that cannot drift
  22. Down to a single formatting object
  23. When to reach for code
  24. Glossary
  25. List of Figures
  26. List of Tables
  27. List of Listings
  28. Bibliography
  29. Index
  30. Search

Chapter 1

Quickstart

Smia builds a manuscript into screen and print PDFs, an EPUB, and a static website, all on the JVM.

Installation

Smia is one command, smia, backed by a single jar that bundles everything: the PDF, EPUB, and site pipelines, the math and diagram renderers, and the site islands’ ClojureScript compiler. It runs on a Java runtime, and the package managers below install one alongside it.

On macOS or Linux, with Homebrew (the tap is added automatically):

brew install leifericf/smia/smia

On Windows, with Scoop:

scoop bucket add java
scoop bucket add smia https://github.com/leifericf/scoop-smia
scoop install smia

Without a package manager, download smia.jar from the repository’s Releases page, install a JDK (17 or later, for example Temurin), and run java -jar smia.jar wherever this manual says smia. jbang users can have both provisioned in one step with jbang app install --name smia <jar URL>.

Check the installation:

smia version

Clojure developers have a fourth route: running Smia from a source checkout, as a git dependency, or as a Clojure CLI tool. The commands chapter covers that track.

A minimal book

Scaffold one:

smia init my-book

This writes a minimal, buildable manuscript into a new my-book/ directory and refuses a directory that already has anything in it. A manuscript is three kinds of file, and the scaffold contains exactly those: one book.edn, one or more chapter source files, and a theme.edn. The smallest useful book.edn is what init writes:

{:book/slug    "my-book"
 :book/title   "My Book"
 :book/author  "Your Name"
 :book/chapters ["chapters/01-introduction.md"]}

The scaffold writes a starter chapters/01-introduction.md to fill that list. A Markdown chapter is prose under a single top-level heading for its title. At its simplest:

# Introduction

Hello from **Smia**.

The equivalent Clojure chapter evaluates to a [:chapter …] form:

[:chapter {:id :intro :title "Introduction"}
 [:p "Hello from " [:strong "Smia"] "."]]

Build it

smia build my-book

With no --edition given, Smia writes the screen and print PDFs under build/my-book/pdf/, alongside an artifacts.edn manifest. --edition selects the website, the EPUB, and the press-ready PDF/X; the editions chapter describes them all. Run the command from inside the book directory and you can drop the path: smia build.

While writing, smia preview my-book rebuilds the book on every save. Previewing the site edition also serves it locally. See the commands chapter.