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

Preface

Smia built every page of this manual from the Markdown sources under manual/.

Smia is written in Clojure, runs on the JVM, and builds one manuscript into several editions at once. The same sources become screen and print PDFs, a press-ready PDF/X, an EPUB, and a website. A few choices shape the tool.

  • A single manuscript and one set of design tokens produce every edition, so a book’s content and appearance are each described once and compiled to what each format needs.
  • The table of contents, the cross-references, figure and table numbering, the index, the bibliography, and the lists of figures, tables, and listings are all generated from the sources.
  • The same manuscript renders to equivalent output every time, with attributes in sorted order and document metadata pinned.
  • The manuscript, the theme, and the rendered document are all plain data structures, and where the portable sugar runs short, a typed escape hatch reaches the full vocabulary of the format being built.
  • Mathematics and diagrams render to SVG while the book builds, so a formula or a figure reads the same in print, in the EPUB, and on the web, with no script or font needed when the book is read.
  • A default website ships no JavaScript, and the optional reading aids are added over plain HTML that still works when scripting is off.

The manual is organized into parts. The first covers authoring, the second covers configuration, theming, and the build commands, and the third covers book production, editions, distribution, and the design of the tool. Three appendices follow: the error catalog, a Clojure primer for authors, and a live chapter that builds its own content tables. Front matter like this preface is numbered in roman numerals, and the body switches to arabic at the first chapter.

The manual exercises the platform that builds it, so it doubles as a regression test. If a feature breaks, this book stops building.