Decisions

Each design or technical decision, why it was made, and when. Newest last.

From the blog script (October 2026)

auto-print started as one script in the author's Dropbox-synced blog folder. These decisions were made there.

1. Read manuscripts as gfm. It matches how GitHub, GitLab and the VS Code preview show the files. A single line break is a soft break, so a manuscript with one sentence per line gives the same book as one with one line per paragraph. This was checked on three full books with pandoc 3.6.1: the epub, html and docx text was identical.
2. Publish only one section of a manuscript (## Writing by default). Manuscripts keep notes, spelling lists and cut scenes next to the story, and these must never reach a reader.
3. The source files are never changed. The build reads them and writes only to the output folder.
4. Collections are an index file with links, not a list of files in the config. The index file is where the author already keeps the story order, so the order lives in one place. A link in an HTML comment is skipped, which is how a story that is not ready is kept out.
5. A story's opening text moves below its title in a collection. Otherwise each story's content warning would land at the end of the previous story.
6. Extra pages are sections of the source file, named in the config. The author did not want a separate file per page. Naming them in the config, instead of recognising fixed names, means a section is never published by accident.
7. The shallowest heading wins when a name is used at several levels. A real case: an ## Info section held ### Characters notes with spoilers, next to a reader-facing ## Characters page. Two headings with the same name at the same level stop the build, because there is no safe way to choose.
8. The epub's flowing layout is built in the markdown, not with pandoc's --shift-heading-level-by. Extra pages need their own epub files (level 1 headings) while the story stays in one file. Doing the shift in the markdown, under a level 1 heading with the book title, gave byte-identical epub files to pandoc's own shift for books without extra pages.
9. Only pandoc's known epub roles are used. pandoc puts dedication, copyright-page and preface in the front matter and appendix in the back matter. An unknown role is treated as story text, so front pages default to preface and back pages to appendix.
10. pandoc extensions attributes, raw_attribute and fenced_divs are on. The assembled markdown uses them to mark the extra pages, the page breaks and the dedication. They were turned on only after checking that none of the existing manuscripts contained { or a line starting with :::, and that the books came out identical.
11. Page breaks are written per format: a raw Word page break in the docx, a page-break div in the html for the pdf, and nothing in the epub, where a new file is a new page.

As a package (2026-10-24)

12. No runtime dependencies. Only Node's built-in modules. The external tools (pandoc, a browser, Kindle Previewer) are run as commands. Fewer dependencies means less upkeep.
13. TypeScript that Node can run directly (erasableSyntaxOnly, .ts imports). The author's blog runs the source from a clone with node src/cli.ts, so there is no build step to forget. Installed packages live in node_modules, where Node does not run .ts files, so the published package runs dist/, compiled by tsc (rewriteRelativeImportExtensions).
14. Every path in the config file is relative to the config file's folder. One rule for source, cover and outDir.
15. author has no built-in default. The blog script defaulted to its own author, which would be wrong for anyone else.
16. The docx dedication style comes from a reference doc (assets/reference.docx). A Word paragraph style is the only way pandoc can center a paragraph in a docx. The file is pandoc's default template plus one style, made by scripts/make-reference-docx.sh. For a book without a dedication, the only change in the docx is one unused style.
17. Tests use Node's built-in test runner, again to avoid dependencies. The pandoc tests check pandoc's syntax tree of the assembled markdown, and skip themselves when pandoc is not installed.