@uniweb/unipress 0.4.28 → 0.4.30

package/docs/publishing/size-and-layout.md

@@ -0,0 +1,152 @@
+# Size and layout
+
+The physical shape of your book — its **trim size**, margins, and typography — is
+set in `document.yml` under `book:`. Pick it once; every build uses it. This page
+explains the choices and how to make them.
+
+> Full field reference: [`book` template](../templates/book.md). This page is the
+> *why* behind the settings.
+
+## Trim size
+
+The trim size is the finished page dimensions after the printer cuts the sheet.
+It's the single most defining physical choice — it sets how your book feels in the
+hand and constrains everything else. Set it with `book.trim`:
+
+```yaml
+book:
+  trim: trade-6x9
+```
+
+### Built-in presets
+
+| Preset | Size | Good for |
+|---|---|---|
+| `trade-6x9` *(default)* | 6 × 9 in | The safe default. Most trade fiction and nonfiction. |
+| `trade-7x10` | 7 × 10 in | Technical books, workbooks, anything with code or wide images. |
+| `crown-octavo` | 7.44 × 9.69 in (189 × 246 mm) | Common UK trade hardcover. |
+| `royal-octavo` | 6.14 × 9.21 in (156 × 234 mm) | Academic and scholarly hardcover. |
+| `a5` | 148 × 210 mm | Compact European paperback; pocket guides. |
+
+Two more sizes exist for the **article** genre — full-size paper for documents and
+proofing copies rather than bound books:
+
+| Preset | Size | Good for |
+|---|---|---|
+| `a4` | 210 × 297 mm | The world's standard paper. A roomy proofing copy. |
+| `letter` | 8.5 × 11 in | US/Canada paper. A roomy proofing copy. |
+
+### A custom size
+
+Any trim your printer supports. Give a width and height (and, if you like,
+margins) instead of a preset name:
+
+```yaml
+book:
+  trim:
+    width: 5in       # a common "mass-market"-ish trade size
+    height: 8in
+    margins: { inside: 0.75in, outside: 0.5in, top: 0.75in, bottom: 0.75in }
+```
+
+You can also start from a preset and nudge one value:
+
+```yaml
+book:
+  trim:
+    preset: trade-6x9
+    margins: { inside: 0.9in }   # more gutter for a thick book
+```
+
+**Pick a size your print-on-demand service offers.** Each service lists its
+supported trim sizes; matching one avoids a custom-size surcharge. Check
+[KDP's list](https://kdp.amazon.com/help/topic/G201834180) or
+[IngramSpark's](https://help.ingramspark.com/hc/en-us/articles/360010301911).
+
+## Margins and the gutter
+
+A bound book needs an **asymmetric** margin: the **inside** (gutter) edge — where
+the pages meet the spine — must be wider than the **outside**, or text disappears
+into the binding. The presets already do this. The four margins:
+
+```yaml
+book:
+  trim:
+    preset: trade-6x9
+    margins: { inside: 0.75in, outside: 0.5in, top: 0.75in, bottom: 0.75in }
+```
+
+**The more pages, the more gutter you need** — a thick book's spine "steals" more
+of the inside margin. Print-on-demand services publish a minimum inside margin by
+page count; a ~300-page 6×9 usually wants at least 0.75–0.875 in inside. Confirm
+against your service's table before you finalize, and widen `inside` if needed.
+
+## Bleed
+
+**Bleed** is art that runs off the edge of the page. Because printers can't cut
+perfectly, anything meant to reach the edge must extend ~0.125 in *past* the trim,
+so the cut never leaves a white sliver.
+
+- **Text interiors need no bleed.** Your words sit inside the margins; unipress
+  emits pages at the exact trim size, which is exactly what print-on-demand wants
+  for a text interior. This is the common case — you don't have to think about it.
+- **Full-bleed interior *images*** (a photo running to the paper edge) are the
+  exception. unipress emits trim-size pages, so it isn't set up for edge-to-edge
+  interior art. Keep interior images within the text block, or ask your printer how
+  they want full-bleed interior pages supplied.
+- **Your cover is where bleed really matters**, and that's handled separately by
+  your print service's cover template — see [covers-and-images.md](./covers-and-images.md#covers).
+
+## Front matter
+
+The pages before Chapter 1 — title, copyright, contents. Toggle them under
+`book.structure`:
+
+```yaml
+book:
+  structure:
+    titlePage: true
+    copyrightPage: true
+    toc: true
+    tocDepth: 2                 # how many heading levels the contents lists
+    frontMatterNumbering: roman # none | roman | arabic
+```
+
+- **`titlePage`** — the title, subtitle, and author, typeset. If your cover art
+  already carries the title (many do), you may want this **off** to avoid repeating
+  it: `titlePage: false`.
+- **`copyrightPage`** — the copyright/imprint page. Pulls from `book.rights`,
+  `book.publisher`, `book.isbn` (see [isbn-and-metadata.md](./isbn-and-metadata.md)).
+- **`toc`** — a generated table of contents from your chapter titles.
+- **`frontMatterNumbering: roman`** is the traditional convention: front matter is
+  numbered i, ii, iii…; Chapter 1 resets to page 1. Use `none` to leave front
+  matter unnumbered, or `arabic` to number straight through.
+
+## Typography
+
+The defaults produce a clean, readable book — you can ship without touching them.
+When you want control, set it under `book.typography`:
+
+```yaml
+book:
+  typography:
+    bodySize: 11pt
+    leading: 0.72em          # line spacing
+    firstLineIndent: 1.4em   # paragraph indent
+    bodyFont: ["EB Garamond", "Georgia"]   # first available wins
+    headingFont: ["EB Garamond", "Georgia"]
+```
+
+- **Fonts are tried in order**; the first one installed on the machine running the
+  compile is used, and unipress embeds it in the PDF. Leave them unset to use the
+  compiler's clean built-in defaults. If you name a font, make sure it's installed
+  where you build.
+- **Body size and leading** are the levers for page count and comfort. 10.5–11 pt
+  with roomy leading reads well in a 6×9.
+- For a classical look with these choices preconfigured, scaffold the **monograph**
+  template instead of tuning by hand: `unipress create my-book --template monograph`.
+
+## Next
+
+- Add your [covers and images](./covers-and-images.md).
+- Produce your [ebook](./ebooks.md) or go to [print](./print.md).

package/docs/troubleshooting.md

@@ -53,7 +53,7 @@ with `paths: { pages: . }`. It's an ordinary config file; edit it freely.
 To write one by hand instead:
 
 ```yaml
-foundation: "@uniweb/book@0.4.1"
+foundation: "@uniweb/book@0.4.2"
 format: pdf
 paths:
   pages: .          # only needed when sections live at the root (no content/ folder)
@@ -200,6 +200,23 @@ The config file's default export is a string, number, array, or something else.
 export default { format: 'pdf' }
 ```
 
+## Cover image (or other config asset) doesn't appear in the output
+
+Not an error — a silent drop. The book compiles, but the front/back cover (or a
+banner/logo declared in config) is missing from the PDF/EPUB.
+
+Config-declared asset paths — `book.covers.front`, `book.covers.back`, and the like —
+are resolved from the top-level config unipress **reads for content collection**: the
+default `document.yml`, or the file you pass to `--document`. They are *not* scanned from
+a `unipress.config.js` supplied via `--config` (that file layers build settings — `out`,
+`format`, `typst` — over the compile, after content is collected).
+
+So if your covers live in `document-book.yml`, build it with `--variant document-book`
+— not `--config document-book.yml`. Confirm with `--verbose`: the `Found N asset references`
+line should count your covers (e.g. 2 more than the body images), and the source-bundle
+`blob:` size should grow by roughly the covers' byte size. Also confirm the files exist at
+the declared path relative to the content directory (e.g. `assets/front.png`).
+
 ## Internal error (exit code 2)
 
 Something unexpected threw — typically a library error or a code path unipress didn't wrap. Re-run with `--verbose` for a stack trace, then open an issue with the trace and a description of the content directory + foundation you're compiling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.4.28",
+  "version": "0.4.30",
   "description": "Compile a content directory into a document (PDF, EPUB, Paged.js HTML, Typst source bundle, DOCX, XLSX) using a Uniweb foundation. Five built-in templates: book, monograph, report, data-report, directory.",
   "type": "module",
   "publishConfig": {
@@ -49,11 +49,11 @@
     "prompts": "^2.4.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "@uniweb/build": "0.14.22",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/build": "0.14.20",
-    "@uniweb/core": "0.7.14",
-    "@uniweb/runtime": "0.8.20",
-    "@uniweb/semantic-parser": "1.1.17"
+    "@uniweb/core": "0.7.15",
+    "@uniweb/semantic-parser": "1.1.17",
+    "@uniweb/runtime": "0.8.21"
   },
   "devDependencies": {
     "vitest": "^4.1.7"

package/src/cli.js

@@ -25,6 +25,9 @@ Commands:
                                                  latex emits a LaTeX source bundle (run latexmk yourself)
                            --foundation <ref>  override document.yml's foundation: field
                            --out <path>        output file (default: ./<dir>.<ext>)
+                           --variant <name>    build an alternate config <name>.yml in <dir>
+                                                 (e.g. --variant document-book) instead of
+                                                 document.yml — several cuts of one manuscript
                            --config <path>     explicit config file (default: <dir>/unipress.config.js)
                            --typst-binary <p>  path to a typst binary (skips managed download)
                            --keep-temp         keep the typst temp dir on failure (for debugging)
@@ -86,6 +89,7 @@ async function main(argv) {
       format: { type: 'string' },
       out: { type: 'string' },
       config: { type: 'string' },
+      variant: { type: 'string' },
       title: { type: 'string' },
       author: { type: 'string' },
       force: { type: 'boolean' },
@@ -131,6 +135,7 @@ async function main(argv) {
           foundation: values.foundation ?? null,
           out: values.out ?? null,
           config: values.config ?? null,
+          variant: values.variant ?? null,
           typstBinary: values['typst-binary'] ?? null,
           keepTemp: !!values['keep-temp'],
           yes: !!values.yes,

package/src/commands/compile.js

@@ -17,10 +17,18 @@ import { detectConfigFile, CONFIG_FILE_NAMES } from '../document-yml.js'
 import { detectBareContent, materializeDocumentYml } from '../materialize.js'
 import { findCatalogEntry } from '../catalog.js'
 
+// `--variant book` → `book.yml`; `--variant print.yaml` → `print.yaml`.
+// The name is used verbatim — no `document-` prefixing — with a `.yml`
+// extension assumed when none is given. Returns null when unset.
+export function variantToConfigFile(variant) {
+  if (!variant) return null
+  return /\.ya?ml$/i.test(variant) ? variant : `${variant}.yml`
+}
+
 // Bare-folder default: the book foundation's `article` genre — a clean
 // single-column A4 paper, the natural shape for a loose folder of markdown.
 const DEFAULT_FOUNDATION =
-  findCatalogEntry('article')?.foundation?.ref ?? '@uniweb/book@0.4.1'
+  findCatalogEntry('article')?.foundation?.ref ?? '@uniweb/book@0.4.2'
 
 // "durable-structured-systems" → "Durable Structured Systems"
 function titleize(slug) {
@@ -98,7 +106,7 @@ async function offerToMaterialize({ sitePath, format, foundation, yes }) {
   return true
 }
 
-export async function compileCommand({ dir, format = null, foundation = null, out = null, config = null, typstBinary = null, keepTemp = false, yes = false, verbose = false } = {}) {
+export async function compileCommand({ dir, format = null, foundation = null, out = null, config = null, variant = null, typstBinary = null, keepTemp = false, yes = false, verbose = false } = {}) {
   if (!dir) {
     process.stderr.write('error: `compile` requires a directory argument\n')
     process.stderr.write('usage: unipress compile <dir> [--format <fmt>] [--foundation <ref>] [--out <path>] [--config <path>] [--typst-binary <path>] [--keep-temp] [--yes] [--verbose]\n')
@@ -106,7 +114,9 @@ export async function compileCommand({ dir, format = null, foundation = null, ou
   }
 
   const sitePath = resolve(dir)
-  if (existsSync(sitePath) && !detectConfigFile(sitePath)) {
+  // `--variant <name>` names an explicit config; don't offer to generate
+  // one (loadContent throws a clear error if the named file is missing).
+  if (!variant && existsSync(sitePath) && !detectConfigFile(sitePath)) {
     const proceed = await offerToMaterialize({ sitePath, format, foundation, yes })
     if (!proceed) process.exit(1)
   }
@@ -121,6 +131,7 @@ export async function compileCommand({ dir, format = null, foundation = null, ou
     foundationRef: foundation,
     outPath: out,
     configPath: config,
+    documentConfig: variantToConfigFile(variant),
     typstBinaryPath: typstBinary,
     keepTemp,
     onProgress

package/src/compile.js

@@ -52,10 +52,13 @@ export async function compile({
   typstBinaryPath: cliTypstBinaryPath = null,
   keepTemp = false,
   configPath: cliConfigPath = null,
+  documentConfig = null,
   onProgress = () => {}
 } = {}) {
   onProgress('loading content...')
-  const { content, sitePath, configFile } = await loadContent(dir)
+  const { content, sitePath, configFile } = await loadContent(dir, {
+    configFile: documentConfig
+  })
   onProgress(`  ${content.pages.length} page(s) from ${sitePath} (${configFile})`)
 
   // A config exists but nothing was collected — almost always the markdown

package/src/content-loader.js

@@ -8,8 +8,8 @@
 // image asset-processor (which eagerly loads sharp's native binding and
 // blows up in a `bun build --compile` binary).
 
-import { existsSync } from 'node:fs'
-import { resolve, join } from 'node:path'
+import { existsSync, readdirSync } from 'node:fs'
+import { resolve, join, basename } from 'node:path'
 import { collectSiteContent, processCollections } from '@uniweb/build/content'
 import { detectConfigFile, CONFIG_FILE_NAMES } from './document-yml.js'
 import { ContentDirectoryError, DocumentYmlError } from './errors.js'
@@ -121,6 +121,21 @@ async function resolveLocalCollections(siteContent, sitePath) {
   }
 }
 
+// Discoverability aid: when a named `--variant` config is missing, list the
+// YAML configs that ARE present so a typo (or a forgotten `.yml`) is easy to
+// spot and fix.
+function listConfigsHint(sitePath) {
+  try {
+    const ymls = readdirSync(sitePath).filter(
+      (f) => f.endsWith('.yml') || f.endsWith('.yaml'),
+    )
+    if (!ymls.length) return ''
+    return `\navailable configs here: ${ymls.join(', ')}`
+  } catch {
+    return ''
+  }
+}
+
 export async function loadContent(dir, options = {}) {
   const sitePath = resolve(dir)
 
@@ -128,17 +143,39 @@ export async function loadContent(dir, options = {}) {
     throw new ContentDirectoryError(`content directory does not exist: ${sitePath}`)
   }
 
-  const configFile = detectConfigFile(sitePath)
-  if (!configFile) {
-    throw new DocumentYmlError(
-      `no ${CONFIG_FILE_NAMES.PRIMARY} (or ${CONFIG_FILE_NAMES.FALLBACK}) found in ${sitePath}`
-    )
+  // An explicit config name (from `--variant`) selects an alternate
+  // top-level config inside the content dir — e.g. a `document-book.yml`
+  // beside the default `document.yml`. It must exist; we don't fall back
+  // to auto-detection when the user named one. Otherwise auto-detect
+  // `document.yml` / `site.yml`.
+  let configFile
+  if (options.configFile) {
+    configFile = options.configFile
+    if (!existsSync(join(sitePath, configFile))) {
+      throw new DocumentYmlError(
+        `variant config not found: ${join(sitePath, configFile)}${listConfigsHint(sitePath)}`
+      )
+    }
+  } else {
+    configFile = detectConfigFile(sitePath)
+    if (!configFile) {
+      throw new DocumentYmlError(
+        `no ${CONFIG_FILE_NAMES.PRIMARY} (or ${CONFIG_FILE_NAMES.FALLBACK}) found in ${sitePath}`
+      )
+    }
   }
 
+  // unipress is a document tool: read any config that isn't the `site.yml`
+  // dogfood fallback with the document profile (content/ + folder mode +
+  // `content:` ordering), regardless of the file's name. So a variant can
+  // be named freely (book.yml, print.yml) and still build as a document.
+  const profile = basename(configFile).startsWith('site') ? 'site' : 'document'
+
   let content
   try {
     content = await collectSiteContent(sitePath, {
       configFile,
+      profile,
       foundationPath: options.foundationPath
     })
   } catch (err) {

package/src/foundations-data.js

@@ -72,8 +72,8 @@ function publicUrl(name, version) {
 }
 
 const BOOK_FOUNDATION = {
-  ref: '@uniweb/book@0.4.1',
-  source: { url: publicUrl('book', '0.4.1') },
+  ref: '@uniweb/book@0.4.2',
+  source: { url: publicUrl('book', '0.4.2') },
 }
 
 const DATA_FOUNDATION = {