accessible-marp-decks 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] — 2026
+
+Version 2 is a ground-up modernisation. The rendered output is now a single, self-contained, responsive, accessible file, and the project ships as an ESM package usable as a CLI, a library, an Eleventy plugin, or a GitHub Action.
+
+### Added
+
+- **Single-file output** — local images are base64-inlined into the page, so a built deck is one self-contained HTML file (`inlineAssets`, `basePath` render options).
+- **Responsive 16:9 scaling** — each fixed-size slide is scaled to the window as one rigid unit via CSS `zoom` (a small inlined script sets the scale factor), so text, spacing, and layout shrink together and nothing reflows. Browser page zoom still enlarges the deck (the script compensates via `devicePixelRatio`), per WCAG 1.4.4.
+- **Layout helpers** — slide-native `box`, `stack`, `cluster`, `columns`, `grid`, `center`, `frame`, `cover`, `sidebar`, and `overlay-centre` classes.
+- **Smarter code-block focus** — code blocks are keyboard-scrollable by default (no-JS safe), and a tiny inlined script removes the tab stop from blocks that don't actually overflow, re-checking on resize.
+- **`build-all <dir>`** CLI command — builds every deck in a folder and writes an accessible landing page linking them. A failing deck doesn't abort the site: the rest are built, the failure is reported, and the command exits non-zero with a summary.
+- **GitHub Action** — a reusable composite `action.yml` plus an example Pages-deploy workflow, so decks can be published without a command line.
+- **Theme template** — `themes/_template.css`, a documented, self-contained starter to copy and recolour.
+- **`high-contrast` theme** — a second bundled theme (pure black/white, auto light/dark).
+- **`runtimeScript` render option** — set `false` to omit the inlined code-block script for strict-CSP hosts.
+- **Tests** (`node:test`) and **CI** covering accessibility invariants, image inlining, scaling, layout helpers, theme resolution, the CLI, and the Eleventy plugin — with 100% line, branch, and function coverage enforced in CI.
+
+### Changed
+
+- Rewritten as **ESM** with package `exports` (`.` and `./eleventy`) and an `accessible-marp` bin.
+- Transforms are **element-scoped** files — `_section.js`, `_img.js`, `_code.js`.
+- The `basic` theme is re-authored in `em` units with automatic light/dark modes.
+- Dependencies trimmed to the five that are actually used.
+- js-beautify is loaded on demand — rendering with `prettify: false` never loads it.
+- Node 24 (LTS) is the development, CI, and Action runtime, pinned in `.nvmrc`; the npm `engines` field is no longer set.
+
+### Fixed
+
+- Code fences without a language (or with an unrecognised one) now escape their content instead of injecting it into the page as raw HTML.
+- Slides with several headings no longer emit duplicate `slide-N` ids or concatenate every heading into the slide's `aria-label` — only the first heading is used. Heading-less slides are labelled `"Slide N"` with no dangling colon.
+- Slide background images (`![bg](…)`) are now base64-inlined like every other image, so decks with backgrounds stay a single self-contained file. The consumed `data-background-image` and `data-marpit-pagination-total` attributes are stripped from the output.
+- Applying a helper to a whole slide with `<!-- _class: … -->` now actually works: Marpit scopes bare class selectors to descendants of the slide, so the documented pattern silently did nothing. Themes now ship slide-level variants (`cover`, `center`, `stack`) written as `section.X`, and Marpit's bookkeeping `data-class` attribute is stripped.
+- The `css` render option no longer requires a `/* @theme */` comment — one is prepended automatically, instead of Marpit rejecting the CSS.
+- Image srcs are treated as URLs when inlining: percent-escapes are decoded (`my%20image.png` finds `my image.png` on disk) and query strings/fragments are ignored, instead of silently leaving a broken reference.
+- The runtime script re-evaluates code-block focus after web fonts finish loading and observes the blocks directly — slides are fixed-size, so a block's overflow can change without the deck resizing.
+- The CLI recognises backslash-separated (Windows) paths as paths rather than deck names, and CI now also runs the suite on Windows.
+- Slides in decks without `paginate: true` are now numbered by position instead of being labelled "Slide undefined".
+
+### Security
+
+- The GitHub Action passes its inputs to the build script via environment variables instead of interpolating `${{ }}` expressions into bash, closing a shell-injection surface.
+
+### Removed
+
+- The `imageWidth` option (images are now sized responsively by CSS).
+- The SASS build and the dead dependencies from 1.x (`node-sass`, `html-minifier`, and others).
+
+[2.0.0]: https://github.com/abbott567/accessible-marp-decks/releases/tag/v2.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Craig Abbott
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/NOTICE

@@ -0,0 +1,21 @@
+Accessible Marp Decks
+Copyright (c) 2026 Craig Abbott
+
+This product is licensed under the ISC License (see LICENSE).
+
+It builds on, and bundles or depends on, the following third-party work:
+
+- Marp / Marpit (https://marp.app/) — MIT License.
+  Used to render Marp markdown into slide HTML and CSS.
+
+- highlight.js (https://highlightjs.org/) — BSD 3-Clause License.
+  Used for syntax highlighting of fenced code blocks.
+
+- The "a11y-light" and "a11y-dark" syntax-highlighting colour schemes by
+  Eric Bailey (https://github.com/ericwbailey/a11y-syntax-highlighting) —
+  MIT License. The bundled themes' code colours are derived from these.
+
+The layout helpers in the bundled themes (box, stack, cluster, columns, grid,
+center, frame, cover, sidebar, overlay-centre) are original CSS written for this
+project using standard CSS grid and flexbox. They are conceptually inspired by
+common layout patterns but do not copy any third-party implementation.

package/README.md

@@ -0,0 +1,181 @@
+# Accessible Marp Decks
+
+Render [Marp](https://marp.app/) markdown slide decks into a **single, self-contained, accessible HTML page** — every slide is a labelled landmark, headings have stable ids, code blocks that scroll are keyboard-focusable, pagination is announced to screen readers, images are inlined, and the whole thing scales to any window in 16:9 without reflowing.
+
+Use it four ways:
+
+- **CLI** — build a deck (or a whole folder) into shareable HTML.
+- **Library** — `import { renderDeck }` and render Marp markdown anywhere.
+- **Eleventy plugin** — drop deck files into an [Eleventy](https://www.11ty.dev/) site.
+- **GitHub Action** — publish decks to GitHub Pages on push, no command line.
+
+This project isn't a replacement for Marp or the VSCode preview extension — it's for **sharing** your slides in an accessible format.
+
+## Requirements
+
+- Node.js 24 (LTS) — the version pinned in [`.nvmrc`](.nvmrc). Older versions may work but aren't tested.
+
+## Install
+
+```sh
+npm install accessible-marp-decks
+```
+
+## Writing slides
+
+Slides are [Marpit markdown](https://marpit.marp.app/markdown). A deck starts with front matter and separates slides with `---`:
+
+```markdown
+---
+title: My Talk
+description: A short description used for the page <title> and meta description.
+paginate: true
+marp: true
+theme: basic
+---
+
+# My Talk
+
+Intro text.
+
+---
+
+## Second slide
+
+More content.
+```
+
+Compose richer slides with the [layout helpers](docs/layouts.md) (`columns`, `grid`, `cluster`, `frame`, …). To preview as you write, install the [Marp for VSCode extension](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode).
+
+## What you get out
+
+A built deck is **one HTML file**. CSS is inlined, images are base64-encoded into the page, and the slides scale to fit the window. Nothing else needs to ship alongside it (except any linked `demos/` pages), so it's trivial to email, host, or attach.
+
+## CLI usage
+
+The package installs an `accessible-marp` binary.
+
+```sh
+# Build a named deck (looked up under examples/decks/<name>/slides.md by default)
+accessible-marp build layouts --theme basic
+
+# Build a specific markdown file to a chosen output directory
+accessible-marp build ./slides.md --out ./public
+
+# Build every deck in a folder into a browsable site with a landing page
+accessible-marp build-all decks --out _site
+
+# List the bundled themes
+accessible-marp themes
+```
+
+Options:
+
+| Flag | Description |
+| --- | --- |
+| `--theme`, `-t` | Theme to use. Defaults to the deck's front-matter `theme`. |
+| `--out`, `-o` | Output directory. Defaults to `dist/decks/<deck>` (or `dist/site` for `build-all`). |
+| `--decks-dir` | Where named decks live. Defaults to `examples/decks`. |
+
+`build` writes a single `slides.html` (plus any `demos/` folder). `build-all` writes each deck to `<out>/<name>/index.html` and an accessible landing page at `<out>/index.html`; if a deck fails, the rest are still built and the command exits non-zero with a summary. The legacy `npm run build deck=<name> theme=<name>` form still works.
+
+## Library usage
+
+```js
+import { renderDeck, renderDeckFile, listThemes } from 'accessible-marp-decks'
+
+const html = await renderDeck(markdownString, { theme: 'basic', basePath: './my-deck' })
+
+// or straight from a file (basePath defaults to the file's directory)
+const html2 = await renderDeckFile('./my-deck/slides.md', { theme: 'basic' })
+
+await listThemes() // ['basic', 'high-contrast']
+```
+
+### `renderDeck(markdown, options)` → `Promise<string>`
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `theme` | front matter, else `basic` | A bundled theme name. |
+| `css` | — | Raw theme CSS, used instead of a bundled theme. An `/* @theme */` comment is added automatically if missing. |
+| `documentCss` | bundled `document.css` | Override the base accessible-layout CSS. |
+| `basePath` | — | Directory used to resolve and inline relative image paths. |
+| `inlineAssets` | `true` | Base64-inline local images for a single-file output. |
+| `lang` | `'en'` | Document `lang` attribute. |
+| `runtimeScript` | `true` | Inline the code-block scrolling enhancement script. Set `false` for strict-CSP hosts. |
+| `prettify` | `true` | Pretty-print the HTML output. |
+
+## Eleventy plugin
+
+Render Marp decks as accessible pages inside an [Eleventy](https://www.11ty.dev/) (3.0+) site.
+
+```js
+// eleventy.config.js
+import accessibleMarp from 'accessible-marp-decks/eleventy'
+
+export default function (eleventyConfig) {
+  eleventyConfig.addPlugin(accessibleMarp, {
+    // theme: 'basic',   // force one theme for all decks (optional)
+  })
+}
+```
+
+By default the plugin registers a **`.deck`** extension, so any `*.deck` file (containing Marp markdown) is built as an accessible deck page. Using a dedicated extension means your site's normal `.md` files are left untouched.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `extension` | `'deck'` | File extension that marks a deck. Set to `'md'` to treat **every** markdown file as a deck (fully overrides Eleventy's markdown rendering). |
+| `theme` | per-deck front matter | Force a theme for all decks. |
+| `lang` | `'en'` | Document language. |
+
+Images are inlined into each page automatically. Companion `demos/` folders (standalone HTML pages your slides link to) are **not** copied by the plugin — add a passthrough copy for them in your Eleventy config if you use them:
+
+```js
+eleventyConfig.addPassthroughCopy('content/**/demos/**')
+```
+
+A working demo lives in [`examples/eleventy-demo`](examples/eleventy-demo) — run it with `npm run demo`.
+
+## GitHub Action
+
+Publish decks to GitHub Pages on every push — no command line. Add one workflow and enable Pages; full walkthrough in [docs/github-action.md](docs/github-action.md).
+
+```yaml
+- name: Build decks
+  uses: abbott567/accessible-marp-decks@v2
+  with:
+    decks-dir: decks
+    out: _site
+- uses: actions/upload-pages-artifact@v5
+  with:
+    path: _site
+```
+
+## Layouts and themes
+
+- **Layout helpers** — `box`, `stack`, `cluster`, `columns`, `grid`, `center`, `frame`, `cover`, `sidebar`, `overlay-centre`. See [docs/layouts.md](docs/layouts.md).
+- **Themes** live in [`themes/`](themes). Two are bundled: **`basic`** (the default) and **`high-contrast`** — both neutral designs with automatic light/dark modes via `prefers-color-scheme`, using the reader's `system-ui` font. To make your own, copy [`themes/_template.css`](themes/_template.css) and recolour it — see [docs/creating-themes.md](docs/creating-themes.md).
+
+## Accessibility
+
+Every rendered deck is a labelled-landmark structure with screen-reader pagination, keyboard-scrollable code blocks, and reflow-free 16:9 scaling. The full list of guarantees is in [docs/accessibility.md](docs/accessibility.md).
+
+## Development
+
+```sh
+npm install
+npm test        # node:test — accessibility, images, scaling, layouts, CLI, Eleventy
+npm run lint    # standard
+npm run build:site   # build the example decks into _site/
+npm run demo    # build the Eleventy demo site
+```
+
+The publishable package is the engine (`src/`) and `themes/`. The `layouts` deck under `examples/decks` is a demo of the layouts the renderer supports and is excluded from the npm tarball.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+[ISC](LICENSE). Third-party credits are in [NOTICE](NOTICE).

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "accessible-marp-decks",
+  "version": "2.0.0",
+  "description": "Render Marp markdown slide decks into a standalone, accessible HTML format. Usable as a CLI, an importable function, or an Eleventy plugin.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./eleventy": "./src/eleventy.js"
+  },
+  "bin": {
+    "accessible-marp": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "themes",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node src/cli.js build",
+    "build:site": "node src/cli.js build-all examples/decks --out _site",
+    "test": "node --test",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude=\"test/**\" --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100",
+    "lint": "standard src test",
+    "demo": "cd examples/eleventy-demo && eleventy"
+  },
+  "keywords": [
+    "marp",
+    "marpit",
+    "accessibility",
+    "a11y",
+    "slides",
+    "presentation",
+    "eleventy",
+    "eleventy-plugin"
+  ],
+  "author": "Craig Abbott",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abbott567/accessible-marp-decks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abbott567/accessible-marp-decks/issues"
+  },
+  "homepage": "https://github.com/abbott567/accessible-marp-decks#readme",
+  "dependencies": {
+    "@marp-team/marpit": "^3.1.3",
+    "cheerio": "^1.0.0",
+    "gray-matter": "^4.0.3",
+    "highlight.js": "^11.10.0",
+    "js-beautify": "^1.15.1"
+  },
+  "peerDependencies": {
+    "@11ty/eleventy": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@11ty/eleventy": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@11ty/eleventy": "^3.0.0",
+    "standard": "^17.1.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { readFile, writeFile, mkdir, cp, stat, readdir } from 'node:fs/promises'
+import { dirname, join, basename, resolve } from 'node:path'
+import { renderDeck, readDeckInfo } from './core/render.js'
+import { listThemes } from './core/themes.js'
+import { escapeHtml } from './core/escape.js'
+
+const USAGE = `accessible-marp — build accessible HTML decks from Marp markdown
+
+Usage:
+  accessible-marp build <deck|path> [--theme <name>] [--out <dir>] [--decks-dir <dir>]
+  accessible-marp build-all <dir> [--theme <name>] [--out <dir>]
+  accessible-marp themes
+  accessible-marp --help
+
+Arguments:
+  <deck|path>          A deck name (resolved under --decks-dir) or a path to a .md file.
+  <dir>                A directory of decks (each a folder containing slides.md).
+
+Options:
+  --theme, -t <name>   Theme to use. Defaults to the deck's front-matter theme.
+  --out, -o <dir>      Output directory. Defaults to dist/decks/<deck> (build)
+                       or dist/site (build-all).
+  --decks-dir <dir>    Where named decks live. Defaults to examples/decks.
+  --help, -h           Show this help.
+
+Examples:
+  accessible-marp build layouts --theme basic
+  accessible-marp build ./slides.md --out ./public
+  accessible-marp build-all examples/decks --out _site
+  npm run build deck=layouts theme=basic`
+
+async function exists (p) {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Accept legacy `key=value` tokens (e.g. `deck=x theme=y`) alongside flags. */
+function extractLegacyTokens (argv) {
+  const legacy = {}
+  const rest = []
+  for (const arg of argv) {
+    const m = /^(deck|theme|out)=(.*)$/.exec(arg)
+    if (m) legacy[m[1]] = m[2]
+    else rest.push(arg)
+  }
+  return { legacy, rest }
+}
+
+/**
+ * Render one deck's markdown to `<outDir>/<htmlName>` and copy any `demos/`.
+ * Returns metadata about the built deck.
+ */
+async function buildOne ({ mdPath, sourceDir, deckName, outDir, theme, htmlName }) {
+  const markdown = await readFile(mdPath, 'utf8')
+  const html = await renderDeck(markdown, { theme, basePath: sourceDir })
+
+  await mkdir(outDir, { recursive: true })
+  await writeFile(join(outDir, htmlName), html)
+
+  // Images are base64-inlined into the page, so only companion `demos/`
+  // (standalone linked HTML pages) need copying next to the output.
+  const demosSrc = join(sourceDir, 'demos')
+  if (await exists(demosSrc)) {
+    await cp(demosSrc, join(outDir, 'demos'), { recursive: true })
+  }
+
+  const info = readDeckInfo(markdown)
+  return { deckName, title: info.title || deckName, description: info.description || '' }
+}
+
+async function buildCommand (deckArg, opts) {
+  const decksDir = opts['decks-dir'] || 'examples/decks'
+
+  // Resolve the markdown source: a path, or a named deck under decksDir.
+  // Anything containing a separator (either flavour, so Windows paths work)
+  // or ending in .md is a path; a bare word is a deck name.
+  let mdPath
+  let deckName
+  let sourceDir
+  if (deckArg.endsWith('.md') || /[\\/]/.test(deckArg)) {
+    mdPath = resolve(deckArg)
+    sourceDir = dirname(mdPath)
+    deckName = basename(mdPath, '.md')
+    // A conventional `<name>/slides.md` should be named after its folder.
+    if (deckName === 'slides') deckName = basename(sourceDir)
+  } else {
+    deckName = deckArg
+    sourceDir = resolve(decksDir, deckName)
+    mdPath = join(sourceDir, 'slides.md')
+  }
+
+  if (!(await exists(mdPath))) {
+    throw new Error(`Deck not found: ${mdPath}`)
+  }
+
+  const outDir = resolve(opts.out || join('dist', 'decks', deckName))
+  await buildOne({ mdPath, sourceDir, deckName, outDir, theme: opts.theme, htmlName: 'slides.html' })
+  console.log(`Built "${deckName}" → ${join(outDir, 'slides.html')}`)
+}
+
+async function buildAllCommand (dir, opts) {
+  const root = resolve(dir)
+  if (!(await exists(root))) throw new Error(`Directory not found: ${root}`)
+
+  const entries = await readdir(root, { withFileTypes: true })
+  const outRoot = resolve(opts.out || join('dist', 'site'))
+
+  const built = []
+  const failures = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const sourceDir = join(root, entry.name)
+    const mdPath = join(sourceDir, 'slides.md')
+    if (!(await exists(mdPath))) continue
+
+    // Each deck becomes /<name>/index.html for clean URLs on a static host.
+    // One broken deck must not abort the site — collect failures and keep going.
+    try {
+      const meta = await buildOne({
+        mdPath,
+        sourceDir,
+        deckName: entry.name,
+        outDir: join(outRoot, entry.name),
+        theme: opts.theme,
+        htmlName: 'index.html'
+      })
+      built.push(meta)
+      console.log(`Built "${entry.name}" → ${join(outRoot, entry.name, 'index.html')}`)
+    } catch (err) {
+      failures.push(entry.name)
+      console.error(`Failed "${entry.name}": ${err.message}`)
+    }
+  }
+
+  if (built.length === 0 && failures.length === 0) {
+    throw new Error(`No decks (folders containing slides.md) found in ${root}`)
+  }
+
+  if (built.length > 0) {
+    await writeFile(join(outRoot, 'index.html'), renderIndex(built))
+    console.log(`Wrote index → ${join(outRoot, 'index.html')} (${built.length} decks)`)
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`${failures.length} of ${built.length + failures.length} decks failed to build`)
+  }
+}
+
+/** A minimal, accessible landing page linking to each built deck. */
+function renderIndex (decks) {
+  const items = decks
+    .sort((a, b) => a.title.localeCompare(b.title))
+    .map(d => `      <li>
+        <a href="./${encodeURIComponent(d.deckName)}/">${escapeHtml(d.title)}</a>
+        ${d.description ? `<p>${escapeHtml(d.description)}</p>` : ''}
+      </li>`)
+    .join('\n')
+
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Slide decks</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <style>
+      body { font-family: system-ui, sans-serif; max-width: 44rem; margin: 0 auto; padding: 2rem 1rem; line-height: 1.5; }
+      ul { list-style: none; padding: 0; }
+      li { margin: 0 0 1.5rem; }
+      a { font-size: 1.25rem; }
+      p { margin: .25rem 0 0; color: #555; }
+      @media (prefers-color-scheme: dark) {
+        body { background: #111; color: #eee; } p { color: #aaa; } a { color: #8ab4f8; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Slide decks</h1>
+      <ul>
+${items}
+      </ul>
+    </main>
+  </body>
+</html>
+`
+}
+
+async function main () {
+  const { legacy, rest } = extractLegacyTokens(process.argv.slice(2))
+
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      theme: { type: 'string', short: 't' },
+      out: { type: 'string', short: 'o' },
+      'decks-dir': { type: 'string' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  })
+
+  if (values.help) {
+    console.log(USAGE)
+    return
+  }
+
+  const command = positionals[0]
+
+  if (command === 'themes') {
+    const themes = await listThemes()
+    console.log(themes.join('\n'))
+    return
+  }
+
+  const opts = {
+    theme: values.theme || legacy.theme,
+    out: values.out || legacy.out,
+    'decks-dir': values['decks-dir']
+  }
+
+  if (command === 'build-all') {
+    const dir = positionals[1]
+    if (!dir) throw new Error('No directory specified. See --help.')
+    await buildAllCommand(dir, opts)
+    return
+  }
+
+  if (command === 'build' || legacy.deck) {
+    const deckArg = positionals[1] || legacy.deck
+    if (!deckArg) throw new Error('No deck specified. See --help.')
+    await buildCommand(deckArg, opts)
+    return
+  }
+
+  console.log(USAGE)
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`)
+  process.exitCode = 1
+})

package/src/core/escape.js

@@ -0,0 +1,16 @@
+/**
+ * Escape a value for safe insertion into HTML text or attribute content.
+ * Nullish values become the empty string. The one escape helper for the whole
+ * codebase — template shell, CLI index page, and highlight fallback all share
+ * the same rules.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml (value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/core/marpit.js

@@ -0,0 +1,29 @@
+import hljs from 'highlight.js'
+import { Marpit } from '@marp-team/marpit'
+import { escapeHtml } from './escape.js'
+
+/**
+ * Create a Marpit instance configured the way this project expects:
+ * HTML enabled, smart typography, and syntax highlighting via highlight.js.
+ *
+ * @returns {import('@marp-team/marpit').Marpit}
+ */
+export function createMarpit () {
+  return new Marpit({
+    markdown: {
+      html: true,
+      linkify: true,
+      breaks: true,
+      typographer: true,
+      highlight (str, lang) {
+        // `ignoreIllegals` means highlight() won't throw for a language we've
+        // already confirmed is registered, so no defensive catch is needed.
+        if (lang && hljs.getLanguage(lang)) {
+          const highlighted = hljs.highlight(str, { language: lang, ignoreIllegals: true }).value
+          return `<pre class="hljs"><code>${highlighted}</code></pre>`
+        }
+        return `<pre class="hljs"><code>${escapeHtml(str)}</code></pre>`
+      }
+    }
+  })
+}