@kensio/colophon 2.2.0 → 2.3.0

package/README.md

@@ -16,6 +16,8 @@ finished work.
   from config, not from any one site's stylesheet.
 - **Multiple sizes from one input** — a 1:1 square plus a 1.91:1 landscape by
   default, or whatever set you configure.
+- **Manifest and meta tags** — a JSON record of what was generated, and the
+  Open Graph and Twitter tags that go with it.
 - **Small, reusable API** — a render core with no filesystem concerns, plus an
   optional content walker and CLI.
 
@@ -25,8 +27,10 @@ finished work.
 pnpm add @kensio/colophon
 ```
 
-`sharp` is a dependency and does the SVG → PNG rasterisation; `shiki` provides
-the grammars and themes for the `code` template.
+`@resvg/resvg-js` is a dependency and does the SVG → PNG rasterisation; `shiki`
+provides the grammars and themes for the `code` template. No headless browser is
+involved, and fonts can be handed to the renderer as files (see
+[Fonts](#fonts)) so a build renders the same image everywhere.
 
 ## Quick start (CLI)
 
@@ -64,19 +68,47 @@ colophon content --config colophon.config.ts
 
 For every file that declares `meta_img_props`, Colophon writes one PNG per
 output size next to it, named `<slug>-<size>.png`
-(`post/index.md` → `post/post-og.png` and `post/post-square.png`). Existing
-files are skipped unless you pass `--overwrite`.
+(`post/index.md` → `post/post-og.png` and `post/post-square.png`).
 
 ```
 colophon [contentDir] [options]
 
-  -c, --config <path>   Config module whose default export is a ColophonConfig
-  -o, --overwrite       Re-render even if the output file already exists
+  -c, --config <path>   Config module whose default export is a ColophonConfig,
+                        or a function returning one
+  -f, --force           Re-render every image, ignoring the stamps
+  -o, --overwrite       Alias for --force
+  --concurrency <n>     How many images to render at once
   -h, --help            Show help
 
   contentDir            defaults to "content"
+  --concurrency         defaults to one per available CPU
 ```
 
+Images are rendered a few at a time rather than all at once, so a tree of a few
+hundred posts does not start a few hundred rasterisations and thrash. The
+default — one per CPU the process can use — suits a build machine that has
+nothing else to do; lower it with `--concurrency` to leave room for whatever
+else is running.
+
+### Rebuilds
+
+Every image Colophon writes carries a stamp — a hash of the props, the config
+and the output size it was rendered from, stored in the PNG itself as a `tEXt`
+chunk. On the next run an image whose stamp still matches is left alone, and
+one whose title, colours, template or size has moved on is rendered again. So
+correcting a single post's title re-renders that post's images and nothing
+else.
+
+There is no cache directory and nothing to keep in sync: delete an image and
+its stamp goes with it. An image Colophon did not write, or one written by an
+older version, has no stamp and is rendered over.
+
+The stamp covers the Colophon version too, since the built-in templates ship
+with it — upgrading the package re-renders the tree once. A custom template is
+covered by its own source code, which means a template that reads something its
+source does not name (a closed-over value, a file it loads itself) can change
+without being noticed; `--force` is the way out.
+
 ## Programmatic use
 
 ### Render from props (core)
@@ -120,7 +152,9 @@ await generate({
   contentDir: "content",
   config: { colors: { brand: "#2563eb" } },
   overwrite: false,
+  concurrency: 4, // defaults to one per available CPU
   onResult: (result) =>
+    // result.url is where it is served, when the placement knows.
     console.log(`${result.skipped ? "skip" : "wrote"} ${result.outputPath}`),
 });
 ```
@@ -220,25 +254,125 @@ export default defineConfig({
 
 `charWidthRatio` is how the layout knows where each token sits, so it must match
 the font actually used — `0.6` suits most monospace faces (Source Code Pro,
-Menlo, DejaVu Sans Mono); Consolas wants about `0.55`. Fonts must be installed
-where `sharp` can see them; the default stack ends in the generic `monospace`
-family so it always resolves to something.
+Menlo, DejaVu Sans Mono); Consolas wants about `0.55`. Give the monospace face
+as a file under `fonts` so the ratio you set is the ratio you get; the default
+stack ends in the generic `monospace` family so it resolves to something
+whatever the machine has.
 
 ## Configuration
 
 All fields are optional; sensible defaults apply.
 
-| Option       | Default                        | Notes                                               |
-| ------------ | ------------------------------ | --------------------------------------------------- |
-| `colors`     | neutral indigo/pink            | `brand`, `brandDark`, `brandWarm`, `foreground`.    |
-| `background` | gradient derived from `colors` | Or a `{ type: "solid" }` / custom gradient.         |
-| `fontFamily` | `Arial, Helvetica, sans-serif` | Uses fonts available to `sharp`/librsvg.            |
-| `footer`     | none                           | Footer text; omit the field for none.               |
-| `badge`      | none                           | Corner badge for `banner`; omit the field for none. |
-| `code`       | `github-dark`, monospace stack | Styling for the `code` template (see above).        |
-| `onWarning`  | `console.warn`                 | Where compromises are reported (see below).         |
-| `sizes`      | `og` + `square`                | Named output sizes (see below).                     |
-| `templates`  | `banner`, `card`, `code`       | Merged over the built-ins.                          |
+| Option        | Default                        | Notes                                               |
+| ------------- | ------------------------------ | --------------------------------------------------- |
+| `colors`      | neutral indigo/pink            | `brand`, `brandDark`, `brandWarm`, `foreground`.    |
+| `background`  | gradient derived from `colors` | Or a `{ type: "solid" }` / custom gradient.         |
+| `fonts`       | none                           | Font files to render with (see below).              |
+| `systemFonts` | `true` until `fonts` is set    | Whether installed fonts are loaded too.             |
+| `fontFamily`  | first font, else `Arial, …`    | Font stack for template text.                       |
+| `footer`      | none                           | Footer text; omit the field for none.               |
+| `badge`       | none                           | Corner badge for `banner`; omit the field for none. |
+| `code`        | `github-dark`, monospace stack | Styling for the `code` template (see above).        |
+| `onWarning`   | `console.warn`                 | Where compromises are reported (see below).         |
+| `sizes`       | `og` + `square`                | Named output sizes, each able to override config.   |
+| `templates`   | `banner`, `card`, `code`       | Merged over the built-ins.                          |
+| `content`     | `meta_img_props`, `.md` files  | How props are read from the tree (see below).       |
+| `placement`   | `beside-content`               | Where images go and what URL they get (see below).  |
+| `manifest`    | none                           | Path to write a JSON manifest to (see below).       |
+| `extra`       | none                           | One-off images not tied to a post (see below).      |
+
+### A config that computes something
+
+The default export can also be a function returning the config, async or not.
+Some configs cannot be written as a literal — brand colours read out of the
+site's own stylesheet, a version pulled from `package.json`, a footer that
+names the current build — and without this such a project has to give up the
+CLI and drive `generate` from a script of its own.
+
+```ts
+// colophon.config.ts
+import { readFile } from "node:fs/promises";
+
+import { defineConfig } from "@kensio/colophon";
+
+export default defineConfig(async () => {
+  const theme = JSON.parse(await readFile("src/theme.json", "utf8"));
+
+  return {
+    colors: { brand: theme.primary, brandDark: theme.primaryDark },
+    footer: "example.com",
+  };
+});
+```
+
+The function takes no arguments: everything it might be handed is either
+already on the command line or a decision the config itself is making. It is
+called once per run, before anything is walked or rendered, and what it returns
+is the config — validated and stamped exactly as a literal one would be.
+
+A module that exports neither is an error rather than a run with the defaults:
+the command line asked for that file, so quietly rendering the whole tree
+without it would be the worst of both.
+
+### Unknown options
+
+The config is closed: an option Colophon does not recognise stops the build
+rather than being ignored. A key nobody reads is otherwise a build that
+succeeds and images that are wrong — the default sizes, the default colours,
+and nothing in the log to say why.
+
+```
+Unknown option "dimensions". Did you mean "sizes"?
+```
+
+Where there is an obvious near miss it is named, including options that have
+been renamed between versions; where there is not, the message lists what is
+valid at that point in the config. Nested objects are checked too and named by
+their path — `code.tabsize`, `sizes[1].heigth`, `background.stops[0].ofset` —
+and everything wrong with a config is reported in one go rather than one run
+at a time.
+
+Two parts stay open on purpose: the names under `templates` are your own, and a
+post's props are read by whichever template understands them.
+
+### Fonts
+
+By default Colophon names font families and hopes the machine has them, which
+is how the same post ends up rendering differently on a laptop, in CI and in a
+container. Point `fonts` at font files instead and the output stops depending
+on the machine:
+
+```ts
+export default defineConfig({
+  fonts: [
+    { family: "Inter", path: "./fonts/Inter-Regular.ttf" },
+    { path: "./fonts/Inter-Bold.ttf" },
+    { path: "./fonts/JetBrainsMono-Regular.ttf" },
+  ],
+  code: { fontFamily: "JetBrains Mono" },
+});
+```
+
+- **One entry per file.** Weight and style are read from the font itself, so a
+  regular and a bold face are two entries and the template's `font-weight`
+  picks between them. Supply the bold face: templates ask for weights up to
+  `900` for titles and badges, and a missing weight is drawn with the face you
+  did supply rather than being synthesised into a fake bold.
+- **`family` is optional** and doesn't affect matching — the family name inside
+  the file does that. Naming it on the first font saves setting `fontFamily`,
+  which otherwise stays on the default stack.
+- **Paths are files**, `.ttf`, `.otf`, `.ttc` or `.otc`, resolved from the
+  working directory when relative. A path that isn't there is an error rather
+  than a silently blank image. To load a font you already have in memory —
+  fetched at build time, or bundled — pass `{ data }` with its bytes instead.
+- **System fonts switch off** as soon as you configure any font, so a family
+  you didn't supply can't quietly resolve to something installed. Set
+  `systemFonts: true` to have both, at the cost of the determinism you came
+  for.
+
+An unknown family falls back to a configured font rather than rendering
+nothing, so a mismatched name shows up as the wrong typeface, not a blank
+image.
 
 ### Warnings
 
@@ -285,12 +419,411 @@ frontmatter (SEO-friendly, keyword-rich), falling back to the file name — or t
 parent directory for `index.*` files. Point `slugField` at a different key, or
 override naming entirely with `generate`'s `outputPath` callback.
 
+#### Slug strategies
+
+Two ways to derive a slug from a path, for sites that address content
+differently. `basename` is the default and unchanged:
+
+| Path                    | `basename` | `route`        |
+| ----------------------- | ---------- | -------------- |
+| `index.md`              | `index`    | `index`        |
+| `blog/my-post.md`       | `my-post`  | `blog/my-post` |
+| `services/iam/index.md` | `iam`      | `services/iam` |
+
+`basename` suits Hugo-style page bundles, where the image belongs beside its
+post. `route` suits a site addressed by route — a docs tree where
+`services/iam/index.md` is served at `/services/iam` and wants an image named to
+match:
+
+```ts
+export default defineConfig({
+  content: { slugStrategy: "route" },
+});
+```
+
+A slug carrying directories is written from the **content root** rather than
+beside the file, so `services/iam` becomes `content/services/iam-og.png`.
+Resolving it beside the file would repeat the directories already in the slug.
+A frontmatter `slug` still wins over either strategy.
+
+### Placement
+
+`outputPath` says where the bytes go and nothing about how anyone reaches them,
+so every site rebuilds that mapping in its own templates — from information
+Colophon had while generating and threw away. A placement says both:
+
+```ts
+export default defineConfig({
+  // Astro, Eleventy, Vite: one directory, served under one prefix.
+  placement: { strategy: "public-dir", dir: "public/og", urlBase: "/og" },
+});
+```
+
+```text
+wrote public/og/my-post-og.png -> /og/my-post-og.png
+```
+
+| Strategy         | Writes                                | Suits                   |
+| ---------------- | ------------------------------------- | ----------------------- |
+| `beside-content` | Next to the post, as it always has    | Hugo-style page bundles |
+| `public-dir`     | Into `dir`, one directory for the lot | Astro, Eleventy, Vite   |
+| `custom`         | Wherever `path` says                  | Anything else           |
+
+The URL comes from `urlBase`, prefixed to the image's path under whatever root
+placed it. **No `urlBase`, no URL** — a directory on disk does not say how, or
+whether, it is served, and a URL Colophon invented would be worse than the gap
+it fills. It can be site-relative (`/og`) or absolute, for images on a CDN.
+
+`custom` works both halves out itself, for a mapping that is nobody else's —
+images under a dated directory, say:
+
+```ts
+placement: {
+  strategy: "custom",
+  path: (file, size) => `public/og/2026/${file.slug}-${size.name}.png`,
+  url: (file, size) => `/og/2026/${file.slug}-${size.name}.png`,
+}
+```
+
+Each result carries the URL as `result.url`, `undefined` where nothing says:
+no `urlBase`, an image placed by `generate`'s `outputPath` callback (which
+still wins, and then the placement no longer describes where the file went), or
+an `extra` that named its own path.
+
+#### Content hashed filenames
+
+Social platforms cache share images hard, and they cache by **URL**. Correct a
+post's image and the old one can keep turning up in feeds for a long time
+afterwards. A hash in the filename is the reliable way round it:
+
+```ts
+placement: { strategy: "public-dir", dir: "public/og", urlBase: "/og", hash: true }
+```
+
+```text
+wrote public/og/my-post-og.ecd0aab2.png -> /og/my-post-og.ecd0aab2.png
+```
+
+Correct the post and the name moves with it, so the URL is one nothing has
+cached:
+
+```text
+wrote public/og/my-post-og.2e7bd5a9.png -> /og/my-post-og.2e7bd5a9.png
+```
+
+The hash is the image's [rebuild stamp](#rebuilds) — its props, config and
+size. Hashing the rendered bytes would be a truer name, but they are not known
+until the image has been rendered, and not rendering the unchanged ones is the
+point of the stamp. It follows that anything the stamp covers moves the name,
+including a Colophon upgrade: the images are re-rendered by that anyway, and a
+fresh URL is the correct answer for an image that may have changed.
+
+It is opt-in because the filename then moves whenever the image does, which not
+every setup wants, and because it leaves the old files behind. **Nothing deletes
+them** — which is the point under a `public-dir` you can rebuild from scratch,
+since a crawler holding the old URL still gets an image, but means a
+`beside-content` tree slowly accumulates them in your content directory. The
+manifest always names the current one, so a site never has to work out which is
+which.
+
+`custom` has no `hash` option: a placement naming its own paths is the one that
+can hash them itself.
+
+A flat placement makes filename collisions much easier to hit — two posts named
+`intro.md` in different sections both want `public/og/intro-og.png`. Colophon
+refuses the build and names both posts rather than letting one overwrite the
+other, which would also leave the pair re-rendering on every build. Pair
+`public-dir` with `slugStrategy: "route"` and each post keeps its section:
+
+```ts
+export default defineConfig({
+  content: { slugStrategy: "route" },
+  placement: { strategy: "public-dir", dir: "public/og", urlBase: "/og" },
+});
+// public/og/blog/intro-og.png -> /og/blog/intro-og.png
+```
+
+### Manifest
+
+Colophon writes PNGs and then goes quiet, so the site works out for itself what
+was generated, where it lives and how big it is — globbing for `*-og.png` to
+find the landscape variant, or hardcoding 1200 and 630 into its meta tags. All
+of that is known while generating. Point `manifest` at a file and it is written
+down:
+
+```ts
+export default defineConfig({
+  placement: { strategy: "public-dir", dir: "public/og", urlBase: "/og" },
+  manifest: "data/colophon.json", // src/data/ for Astro, _data/ for Eleventy
+});
+```
+
+```json
+{
+  "version": 1,
+  "pages": {
+    "blog/my-post": {
+      "images": {
+        "og": {
+          "url": "/og/blog/my-post-og.png",
+          "width": 1200,
+          "height": 630
+        },
+        "square": {
+          "url": "/og/blog/my-post-square.png",
+          "width": 1200,
+          "height": 1200
+        }
+      },
+      "widest": "og",
+      "alt": "My post"
+    }
+  }
+}
+```
+
+Every generator in scope reads JSON as native data: Hugo picks it up from
+`data/`, Astro imports it, Eleventy and Jekyll read `_data/`, Zola has
+`load_data`. Which makes the meta tags a lookup rather than a convention:
+
+```ts
+const page = manifest.pages["blog/my-post"];
+const image = page.images[page.widest];
+// <meta property="og:image" content={image.url}>
+// <meta property="og:image:width" content={image.width}>
+// <meta name="twitter:card" content={image.width / image.height > 1.5
+//   ? "summary_large_image" : "summary"}>
+```
+
+- **Pages are keyed by slug** — what the site addresses a page by, which under
+  `slugStrategy: "route"` is the route itself. Two pages cannot share one, and
+  a build that would need them to fails saying so, since a lookup that returned
+  the wrong post's image is worse than no manifest at all.
+- **`widest`** names the most landscape image by aspect ratio, ties going to
+  the size configured first. It is what a `summary_large_image` card wants, and
+  the check every site currently writes for itself. Note that og (1200×630) and
+  square (1200×1200) are equally _wide_, so comparing widths would pick either.
+- **`url`** is absent where the placement knows none — see
+  [Placement](#placement). The dimensions are always there.
+- **`alt`** comes from the props' title, and is absent for a page without one.
+- **`extra` images are not pages**, so they are not listed. A project that named
+  the output path of one already knows where it is.
+
+The manifest describes what exists, not what a given run did: a rebuild that
+skips every image still writes the whole thing. Pages and sizes are sorted, so
+a manifest committed to a repository changes only when the build does.
+
+### Social meta tags
+
+Generating the image is half the job — the site still has to write the tags,
+and every site ends up with slightly different results. Given the manifest,
+that is a lookup:
+
+```ts
+import { metaTags, metaTagsHtml } from "@kensio/colophon/meta";
+import manifest from "./data/colophon.json";
+
+const site = { baseUrl: "https://example.com" };
+
+metaTagsHtml(manifest, "blog/my-post", site);
+```
+
+```html
+<meta
+  property="og:image"
+  content="https://example.com/og/blog/my-post-og.png"
+/>
+<meta property="og:image:width" content="1200" />
+<meta property="og:image:height" content="630" />
+<meta property="og:image:alt" content="My post" />
+<meta name="twitter:card" content="summary_large_image" />
+<meta
+  name="twitter:image"
+  content="https://example.com/og/blog/my-post-og.png"
+/>
+<meta name="twitter:image:alt" content="My post" />
+```
+
+`metaTags` returns the same set as objects, for a component that spreads them
+— Open Graph names its tags with `property` and Twitter with `name`, so the
+type keeps them apart and `<meta {...tag} />` is right either way:
+
+```jsx
+{
+  metaTags(manifest, slug, site).map((tag) => <meta {...tag} />);
+}
+```
+
+- **The card type follows the image.** `summary_large_image` when the page's
+  widest image is at least 1.5:1 — which the 1.91:1 Open Graph landscape and
+  the 2:1 Twitter size both clear — and `summary` otherwise, since a square
+  shown as a large card is cropped. Sites usually hardcode whichever answer
+  suited the image they had.
+- **`baseUrl` makes the URL absolute**, which Open Graph needs: a crawler reads
+  the tag out of the page and has nothing to resolve a relative URL against. A
+  URL that is already absolute, from a CDN `urlBase`, is left alone.
+- **Alt text goes to both platforms.** Twitter reads `twitter:image:alt` rather
+  than falling back to the Open Graph one, so emitting only the latter means no
+  alt text where most of the sharing happens.
+- **A page with no share image gets no tags** — an empty array, an empty string
+  — rather than an error. Not every page has one, and a template asking should
+  not have to know which in advance.
+
+Import it from `@kensio/colophon/meta` rather than the package root: emitting
+tags reads a JSON file, and a site's templates should not load a rasteriser and
+a syntax highlighter to write a `<head>`.
+
+### Per-size config
+
+Some settings only make sense per size. `code.minFontScale` is the clearest
+case: a 1:1 square and a 1.91:1 landscape have very different amounts of
+vertical room, so a snippet that fits one gets truncated in the other. A size
+can carry its own overrides, applied only when rendering it:
+
+```ts
+export default defineConfig({
+  colors: { brand: "#2563eb" },
+  code: { theme: "github-dark" },
+  sizes: [
+    SIZE_PRESETS.square,
+    { ...SIZE_PRESETS.og, code: { minFontScale: 0.013 } },
+  ],
+});
+```
+
+One pass over the content tree, one config file. The alternative is running
+`generate` once per size with a different config each time, which re-walks and
+re-parses everything for each.
+
+Overridable: `colors`, `background`, `fontFamily`, `footer`, `badge`, `code` —
+what a template reads while drawing. Not overridable: `fonts`, `systemFonts` and
+`templates`, which are shared build inputs rather than part of the picture, and
+`onWarning`, which is where messages go rather than what they say. A size naming
+one of those is an unknown-option error, not a setting that quietly does
+nothing. `fontFamily` is overridable because it picks from the fonts already
+loaded; supplying different font _files_ per size is not the same thing.
+
+`colors` and `code` **merge** over their config-level counterparts, so the
+example above keeps `github-dark` and changes only the minimum font size. Any
+single shade can be overridden on its own — `colors: { foreground: "#111827" }`
+on one size keeps the brand palette and changes just the text colour. The
+rest **replace**: a `background` is a union whose variants have different keys,
+so merging half of one onto half of another would produce a background that is
+neither, and `badge` carries a required `text` a partial override could not
+supply.
+
+Overrides are part of an image's rebuild stamp, so changing one re-renders that
+size and leaves the others alone.
+
+### One-off images
+
+Not every image belongs to a post. A package card, a repository social preview
+and a home page share image all want the same brand and the same templates, and
+none of them has a markdown file behind it. List them under `extra` and the
+build renders them alongside the tree:
+
+```ts
+export default defineConfig({
+  colors: { brand: "#2563eb" },
+  footer: "example.com",
+  extra: [
+    {
+      props: {
+        template: "banner",
+        title: "@kensio/colophon",
+        version: "2.0.0",
+      },
+      output: "public/npm-card.png",
+    },
+    {
+      props: {
+        template: "card",
+        title: "colophon",
+        subtitle: "social meta images",
+      },
+      output: "public/repo-preview.png",
+      size: {
+        name: "repo",
+        width: 1280,
+        height: 640,
+        footer: "github.com/KensioSoftware/colophon",
+      },
+    },
+  ],
+});
+```
+
+`output` is the path to write, relative to the working directory, and any
+directories it names are created. It is the whole path: an extra image has no
+post to sit beside, so `generate`'s `outputPath` callback is not consulted and
+nothing is appended to the filename. An extra that would land on another image
+in the same build stops it before anything is written — two images sharing a
+path do not merely lose one of themselves, they each stamp the file and so
+re-render on every build afterwards.
+
+`size` is an output size like any other, [overrides](#per-size-config) and all —
+that is how the preview above gets its own footer without adding an entry to
+`sizes` that every post would then be rendered at. Leave it out and the image
+takes the first configured size, which for the card above is the default `og`
+1200×630.
+
+Extras are stamped and skipped exactly as content images are, so editing one
+card's title re-renders that card and leaves the rest of the build alone. They
+are reported by `onResult` too, with `contentPath` left `undefined`: there is no
+post behind them to name.
+
 ### Frontmatter shape
 
 By default Colophon reads a `meta_img_props` object and a `template` field
-within it, plus a top-level `slug`. All are configurable via walk options
-(`propsKey`, `templateField`, `defaultTemplate`, `slugField`, `extensions`) so
-you can match an existing convention.
+within it, plus a top-level `slug`. All are configurable under `content`
+(`propsKey`, `templateField`, `defaultTemplate`, `slugField`, `slugStrategy`,
+`extensions`) so you can match an existing convention.
+
+### Using the frontmatter you already have
+
+A site with 200 existing posts gets no images until someone adds a props block
+to 200 files. Most posts already carry the fields an image needs, just under
+different names — so map them instead:
+
+```ts
+export default defineConfig({
+  content: {
+    defaultTemplate: "banner",
+    props: (frontmatter) =>
+      frontmatter.draft === true
+        ? undefined
+        : { title: frontmatter.title, subtitle: frontmatter.description },
+  },
+});
+```
+
+Point it at your content directory and the site gets its images, without
+editing a single post.
+
+**Returning `undefined` skips a post.** That is the filter for drafts, section
+indexes and anything else in the tree that is not a page worth sharing —
+without it, mapping frontmatter means an image for every markdown file there
+is.
+
+**An explicit props block still wins, field by field.** A post that wants a
+different subtitle writes just that:
+
+```yaml
+---
+title: Colophon 2.3.0
+description: Autogenerated release notes
+meta_img_props:
+  subtitle: Per-size config, frontmatter mapping
+---
+```
+
+The title still comes from the mapper; only the subtitle is overridden. A post
+declaring a block is never skipped, even if the mapper would have skipped it —
+asking for an image outright is the stronger signal.
+
+`content` lives in the config module because a `props` mapper is a function and
+cannot be passed as a CLI flag. `generate`'s `walk` option is the programmatic
+equivalent and takes precedence where both are given.
 
 ## Sample output
 
@@ -350,7 +883,10 @@ Adding the `code` template made two small breaking changes:
 - `pnpm lint` — ESLint + Prettier check.
 - `pnpm fmt` — auto-fix.
 - `pnpm samples` — regenerate the README sample images into `docs/samples/`.
-- `pnpm check` — format, typecheck and test with coverage (run before committing).
+- `pnpm fta` — [FTA](https://ftaproject.dev) maintainability scores for `src/`,
+  failing on any file that scores 50 or above.
+- `pnpm check` — format, FTA, typecheck and test with coverage (run before
+  committing).
 
 ## License
 

package/dist/cli/args.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The parsed command line.
+ */
+export interface CliArgs {
+    readonly contentDir: string;
+    readonly configPath: string | undefined;
+    readonly overwrite: boolean;
+    readonly concurrency: number | undefined;
+}
+/** Help text for `--help`, and for a run that asks for nothing else. */
+export declare const usage = "colophon \u2014 generate social meta images from frontmatter\n\nUsage:\n  colophon [contentDir] [options]\n\nImages carry a stamp of the props, config and size they came from, so a rebuild\nrenders only the ones that have actually changed.\n\nOptions:\n  -c, --config <path>   Load a config module. Its default export is either a\n                        ColophonConfig or a function (async or not) returning\n                        one, for a config that has to compute something.\n  -f, --force           Re-render every image, ignoring the stamps\n  -o, --overwrite       Alias for --force\n  --concurrency <n>     How many images to render at once\n  -h, --help            Show this help\n\nDefaults:\n  contentDir            content\n  --concurrency         one per available CPU";
+/** Read the command line into the options `generate` takes. */
+export declare function parseCliArgs(argv: readonly string[]): CliArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,wEAAwE;AACxE,eAAO,MAAM,KAAK,sxBAmB4B,CAAC;AAwB/C,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4B7D"}