diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6f6a8c0..d60f304 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -38,7 +38,7 @@ jobs:
       - run: npm test
         working-directory: vs-code-extension
 
-  test-html-conversion:
+  test-publish:
     needs: test-common
     runs-on: ubuntu-latest
     steps:
@@ -47,42 +47,27 @@ jobs:
         with:
           node-version: '20'
           cache: 'npm'
-          cache-dependency-path: html-conversion/package-lock.json
+          cache-dependency-path: publish/package-lock.json
       - run: npm ci
         working-directory: common
       - run: npm ci
-        working-directory: html-conversion
+        working-directory: publish
       - run: npm test
-        working-directory: html-conversion
+        working-directory: publish
 
   build-docs:
-    needs: test-html-conversion
+    needs: test-publish
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
-          cache-dependency-path: html-conversion/package-lock.json
-      - run: npm ci
-        working-directory: common
-      - run: npm ci
-        working-directory: html-conversion
-      - run: npm run build
-        working-directory: html-conversion
-      - run: >
-          npm run convert --
-          --input ../docs-src/pages
-          --output ../docs
-          --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css
-          --stylesheet docs.css
-          --asset ../docs-src/docs.css
-        working-directory: html-conversion
+      - run: npx @appsoftwareltd/asnotes-publish --config docs-src/asnotes-publish.notes.json
       - uses: actions/upload-pages-artifact@v3
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
         with:
-          path: docs
+          path: docs-src/notes-publish
 
   deploy-pages:
     needs: build-docs
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..e6bfec8
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,6 @@
+{
+    "as-notes.rootDirectory": "docs-src",
+    "markdown.copyFiles.destination": {
+        "**/*.md": "/docs-src/assets/images/${fileName}"
+    }
+}
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index beac417..115084b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to AS Notes will be documented here.
 
 ## Pending Release
 
+## [2.2.8] - 2026-03-24
+
+- Feature: Publishing to static HTML sites from AS Notes, including npm package for CI/CD.  
+
 ## [2.2.7] - 2026-03-23
 
 - Feature: Move to offline licence activation for licence keys.
diff --git a/README.md b/README.md
index 8a0c6b4..dfe5809 100644
--- a/README.md
+++ b/README.md
@@ -755,9 +755,9 @@ The repository is structured as a monorepo with three packages:
 |---|---|
 | `common/` | Shared wikilink parsing library (`Wikilink`, `WikilinkService`, `MarkdownItWikilinkPlugin`) |
 | `vs-code-extension/` | The VS Code extension |
-| `html-conversion/` | CLI utility that converts an AS Notes notebook (markdown + wikilinks) to static HTML |
+| `publish/` | CLI utility that converts an AS Notes notebook (markdown + wikilinks) to static HTML |
 
-Documentation source lives in `docs-src/` (an AS Notes workspace). The `html-conversion` tool converts it to `docs/`.
+Documentation source lives in `docs-src/` (an AS Notes workspace). The `publish` tool converts it to `docs/`.
 
 ### VS Code Extension
 
@@ -772,40 +772,92 @@ npm run lint     # Type-check
 
 ### HTML Conversion
 
+The converter is published as an npm package:
+
+```bash
+npx asnotes-publish --config ./asnotes-publish.json
+```
+
+For development from source:
+
 ```bash
-cd html-conversion
+cd publish
 npm install
 npm run build
-npm run convert -- --input ../docs-src/pages --output ../docs
+npm run convert -- --input ../docs-src/pages --output ../docs --default-public
 ```
 
 The conversion:
 
-- Scans the input directory for `.md` files
+- Scans the input directory recursively for `.md` files
 - Resolves `[[wikilinks]]` to relative `.html` links
-- Generates a `<nav>` sidebar on each page
-- Creates placeholder pages for missing wikilink targets with a "This page has not been created yet" message
+- Generates a sidebar `<nav>` on each page (docs and blog layouts)
+- Filters pages by `public: true` front matter (or all pages with `--default-public`)
+- Always excludes `.enc.md` (encrypted) files from output
+- Creates placeholder pages for missing wikilink targets
 - Wipes the output directory before each run
+- Generates `sitemap.xml` and `feed.xml`
+
+**Config file** (recommended):
+
+Create `asnotes-publish.json` in your notes root:
+
+```json
+{
+    "inputDir": "./pages",
+    "outputDir": "../docs",
+    "defaultPublic": true,
+    "layout": "docs",
+    "theme": "default",
+    "baseUrl": "",
+    "includes": "./includes"
+}
+```
 
-**Styling** (optional):
+Then run with `--config`:
 
-| Flag | Description |
+```bash
+npm run convert -- --config ../asnotes-publish.json
+```
+
+**Layouts:**
+
+| Layout | Description |
 |---|---|
-| `--stylesheet <url>` | Injects a `<link rel="stylesheet">` into every page's `<head>`. Repeatable; tags appear in order. Accepts CDN URLs or relative paths (e.g. `docs.css`). |
-| `--asset <file>` | Copies a local file into the output directory. Use with `--stylesheet` to reference local CSS by filename. Repeatable. |
+| `docs` (default) | Sidebar navigation + content area with TOC |
+| `blog` | Sidebar navigation + narrower centered content + date metadata |
+| `minimal` | Single-column, no navigation |
 
-Example with `github-markdown-css` and a custom local stylesheet:
+Custom layouts can be placed in the includes directory as `{layoutName}.html` with `{{content}}`, `{{nav}}`, `{{toc}}`, `{{title}}`, `{{header}}`, `{{footer}}`, `{{stylesheets}}`, `{{meta}}`, `{{date}}`, `{{base-url}}` tokens.
 
-```bash
-npm run convert -- \
-  --input ../docs-src/pages \
-  --output ../docs \
-  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css \
-  --stylesheet docs.css \
-  --asset ../docs-src/docs.css
-```
+**Themes:**
+
+| Theme | Description |
+|---|---|
+| `default` | Light theme with CSS Grid sidebar layout |
+| `dark` | Dark theme with CSS Grid sidebar layout |
+
+Both themes output formatted, human-editable CSS (`theme-{name}.css`). They use a 220px sidebar with sticky positioning, responsive collapse to single-column below 700px.
 
-Content is always wrapped in `<article class="markdown-body">`, making it natively compatible with `github-markdown-css`.
+**CLI flags:**
+
+| Flag | Description |
+|---|---|
+| `--config <path>` | Load settings from a publish config JSON file |
+| `--input <dir>` | Input directory containing `.md` files |
+| `--output <dir>` | Output directory for generated HTML |
+| `--layout <name>` | Layout template: `docs`, `blog`, `minimal` (default: `docs`) |
+| `--layouts <path>` | Directory containing editable layout templates |
+| `--theme <name>` | Built-in CSS theme: `default`, `dark` |
+| `--includes <path>` | Directory for custom headers and footers |
+| `--stylesheet <url>` | Additional stylesheet (repeatable). CDN URLs or relative paths |
+| `--asset <file>` | Copy a local file into the output directory (repeatable) |
+| `--base-url <path>` | Base URL prefix for all links |
+| `--default-public` | Publish all pages unless `public: false` |
+| `--default-assets` | Copy all assets unless `assets: false` |
+| `--retina` | Generate retina-compatible image markup |
+| `--include-drafts` | Include pages with `draft: true` |
+| `--exclude <dirname>` | Exclude directories from scanning (repeatable) |
 
 In CI, the `build-docs` job runs the same steps automatically on push/PR to `main` (see `.github/workflows/ci.yml`).
 
@@ -842,13 +894,34 @@ npx @vscode/vsce publish
 
 ```bash
 git add .
-git commit -m "Release v2.2.7"   # change version
-git tag v2.2.7                   # change version
+git commit -m "Release v2.2.8"   # change version
+git tag v2.2.8                   # change version
 git push origin main --tags
 ```
 
 Pushing the tag triggers the [Release workflow](.github/workflows/release.yml), which creates a GitHub Release automatically with auto-generated release notes and the VS Code Marketplace install link.
 
+### Publishing the npm CLI (`asnotes-publish`)
+
+**Step 1 - bump the version**
+
+Update `version` in `publish/package.json`.
+
+**Step 2 - build and publish**
+
+```bash
+cd publish
+npm run build
+npm login
+npm publish
+```
+
+**Step 3 - verify**
+
+```bash
+npx asnotes-publish --help
+```
+
 ## Agent Skills
 
 An [agent skill](https://skills.sh/) is available for AS Notes. Install it to give your AI assistant (GitHub Copilot, Claude, etc.) full knowledge of the extension — wikilink syntax, commands, settings, keyboard shortcuts, and more.
diff --git a/TECHNICAL.md b/TECHNICAL.md
index e8515e1..73ba643 100644
--- a/TECHNICAL.md
+++ b/TECHNICAL.md
@@ -169,7 +169,7 @@ as-notes/
 │   └── test/
 │       └── WikilinkService.test.ts  # 23 tests
 ├── vs-code-extension/       # VS Code extension (imports from common via file: dep)
-├── html-conversion/         # CLI: markdown+wikilinks → static HTML
+├── publish/         # CLI: markdown+wikilinks → static HTML
 │   ├── src/
 │   │   ├── convert.ts       # CLI entry point (--input, --output, --stylesheet, --asset)
 │   │   └── FileResolver.ts  # Flat-file wikilink→href resolver
@@ -181,7 +181,7 @@ as-notes/
 
 ### Cross-package dependency
 
-`vs-code-extension` and `html-conversion` both depend on `as-notes-common` via `"file:../common"` in `package.json`. This creates a symlink in `node_modules/as-notes-common` — no npm publish needed. esbuild resolves the symlink and bundles the shared code.
+`vs-code-extension` and `publish` both depend on `as-notes-common` via `"file:../common"` in `package.json`. This creates a symlink in `node_modules/as-notes-common` — no npm publish needed. esbuild resolves the symlink and bundles the shared code.
 
 ### VS Code extension
 
@@ -200,12 +200,26 @@ The build script (`build.mjs`) copies the `sql-wasm.wasm` binary to `dist/` alon
 A standalone CLI tool for converting an AS Notes workspace (markdown files with `[[wikilinks]]`) into static HTML:
 
 - **FileResolver** — scans a directory for `.md` files, builds a case-insensitive filename→href lookup map (same semantics as the extension: spaces URL-encoded). Tracks missing targets during resolution and exposes them via `getMissingTargets()` so placeholder pages can be generated.
-- **convert.ts** — CLI entry point. Args: `--input <dir>`, `--output <dir>`, `--stylesheet <url>` (repeatable), `--asset <file>` (repeatable). Wipes the output directory, copies any assets, runs markdown-it with the shared `wikilinkPlugin`, wraps each page in an HTML shell with `<nav>` sidebar, writes `.html` files. After converting real pages, generates placeholder pages for any missing wikilink targets with a "This page has not been created yet" message and the same nav sidebar.
-- **Styling flags** — `--stylesheet` injects `<link rel="stylesheet" href="...">` tags into every page's `<head>` (CDN URL or relative path). `--asset` copies a local file to the output directory. Zero tags if no `--stylesheet` flags are passed — completely unstyled by default. Content is always wrapped in `<article class="markdown-body">` for compatibility with `github-markdown-css`.
-- **Nav generation** — `index.html` appears as "Home", other pages sorted alphabetically. Semantic markup with class names: `site-nav`, `nav-current`, `markdown-body` (on article), `missing-page`.
-- **CI integration** — the `build-docs` job in `.github/workflows/ci.yml` builds and runs the conversion (`docs-src/pages/` → `docs/`) passing the CDN stylesheet and the local `docs-src/docs.css` asset.
+- **convert.ts** — CLI entry point. Args: `--input <dir>`, `--output <dir>`, `--config <path>`, `--stylesheet <url>` (repeatable), `--asset <file>` (repeatable), `--layout <name>`, `--layouts <path>`, `--theme <name>`, `--includes <path>`, `--base-url <path>`, `--default-public`, `--default-assets`, `--retina`, `--include-drafts`, `--exclude <dirname>` (repeatable). Wipes the output directory, copies any assets, runs markdown-it with the shared `wikilinkPlugin`, wraps each page in an HTML shell with `<nav>` sidebar, writes `.html` files. After converting real pages, generates placeholder pages for any missing wikilink targets and the same nav sidebar. Files ending in `.enc.md` (encrypted notes) are always excluded from scanning.
+- **Config file** — `--config <path>` loads settings from an `asnotes-publish.json` file. CLI flags override config values. When `--config` is given without `--input`, defaults to the config file's parent directory.
+- **Layouts** — three built-in layouts: `docs` (sidebar nav + content area, default), `blog` (sidebar nav + narrower centered content + date metadata), `minimal` (no nav, single-column). The layout determines the HTML template structure. Per-page layout override via `layout` front matter field. Custom layouts can be placed in the includes directory as `{layoutName}.html`.
+- **Themes** — two built-in themes: `default` (light) and `dark`. Both use a CSS Grid sidebar layout (220px nav column + flexible content) with explicit 3-row grid (`auto 1fr auto`) for header/nav+content/footer placement, sticky sidebar, responsive collapse to single column below 700px. Theme CSS is written as a formatted, human-editable file (`theme-{name}.css`) to the output directory. The blog layout gets a narrower centered content column; the minimal layout fills the full width (no sidebar since no nav).
+- **Includes** — `--includes <path>` specifies a directory for custom layouts, headers (`header.html`), and footers (`footer.html`). Partials support `{{base-url}}` and `{{title}}` tokens. Custom layout files override built-in layouts when they share the same name.
+- **Styling flags** — `--stylesheet` injects `<link rel="stylesheet" href="...">` tags into every page's `<head>` (CDN URL or relative path). `--asset` copies a local file to the output directory. Theme CSS is prepended to the stylesheet list so it loads first.
+- **Nav generation** — `index.html` appears as "Home", other pages sorted alphabetically. Semantic markup with class names: `site-nav`, `nav-current`, `markdown-body` (docs), `blog-post` (blog), `missing-page`. Auto-generated index pages (when no `index.md` exists) are built as direct HTML links. Wikilink brackets (`[[`/`]]`) are stripped from all display names in the nav and from page titles.
+- **Front matter** — supports `public`, `title`, `order`, `description`, `layout`, `assets`, `retina`, `draft`, `date`, `slug`, `toc` fields. Pages are filtered by `public: true` (or all pages with `--default-public`). The `slug` field controls the output filename. The `toc` field generates a table of contents.
+- **CI integration** — the `build-docs` job in `.github/workflows/ci.yml` builds and runs the conversion (`docs-src/pages/` -> `docs/`).
 - **npm script** — `npm run convert -- --input <dir> --output <dir> [--stylesheet <url>]... [--asset <file>]...` runs the built CLI from `dist/convert.js`.
-- **`docs-src/docs.css`** — AS Notes-specific stylesheet (not distributed with the tool). CSS grid layout (`220px nav | 1fr content`), styled nav with active state, `prefers-color-scheme: dark` dark mode, responsive single-column collapse below 700 px.
+- **`docs-src/docs.css`** — AS Notes documentation-specific stylesheet (not distributed with the tool). CSS grid layout (`220px nav | 1fr content`), styled nav with active state, `prefers-color-scheme: dark` dark mode, responsive single-column collapse below 700px.
+
+### Publish service (VS Code extension)
+
+`PublishService.ts` provides the VS Code integration for HTML publishing:
+
+- **Wizard** — 9-step QuickPick/InputBox flow: default-public, default-assets, layout, theme, base URL, input dir, output dir, layouts dir, includes dir. Config is saved to `asnotes-publish.json` (or `asnotes-publish.{dirName}.json` for subdirectory inputs).
+- **Multi-site** — `discoverConfigFiles()` finds all `asnotes-publish*.json` files. The publish command always shows a picker when configs exist, with a "Publish All" option for multiple configs.
+- **Scoped directories** — the wizard creates layouts and includes directories scoped to the input directory name (`asnotes-publish.layouts.{inputDirName}` / `asnotes-publish.includes.{inputDirName}` for subdirectory inputs, `asnotes-publish.layouts` / `asnotes-publish.includes` for root), aligning with the config naming convention. The layouts wizard step scaffolds editable copies of all three built-in layouts (`docs.html`, `blog.html`, `minimal.html`).
+- **Config defaults** — `withDefaults()` ensures all fields are written to the JSON with sensible defaults, making the file self-documenting and human-editable.
 
 ---
 
@@ -277,8 +291,6 @@ If a user opens an excluded file (e.g. via the command palette) and triggers the
 
 `ignoreService` is kept as a module-level variable (alongside `indexService` and `indexScanner`) and is set to `undefined` in `exitFullMode()`. In `initWorkspace()`, a temporary `IgnoreService` is constructed (after creating the file) and passed to the one-time `IndexScanner` used for the initial full scan, so newly initialised workspaces also respect default exclusions immediately.
 
-
-
 ```sql
 CREATE TABLE pages (
     id INTEGER PRIMARY KEY,
@@ -758,6 +770,7 @@ The kanban board feature provides a visual task management UI within VS Code. It
 ### File structure
 
 ```
+
 kanban/
   <board-slug>/
     board.yaml                              ← BoardConfig (name, lanes, users, labels)
@@ -766,6 +779,7 @@ kanban/
     assets/
       <card-id>/
         <filename>                          ← attached files
+
 ```
 
 Board slugs and lane slugs are lowercased, with non-alphanumeric characters replaced by hyphens. The `assets/` directory is excluded from lane scanning. The `archive/` lane slug is reserved and excluded from the board config lanes list.
@@ -954,6 +968,7 @@ The editor panel webview (`src/webview/kanban.ts`). Compiled to `dist/webview/ka
 **Card rendering:** Each lane column is rendered with its cards sorted by `sortOrder` (falling back to the `created` timestamp). Cards show priority badge, title, assignee, labels, and due date.
 
 **Drag and drop:**
+
 - Cards are draggable between lanes. On drop, a `moveCard` message is sent with the new lane and an interpolated `sortOrder` (midpoint between neighbours, or ±1 at boundaries).
 - Files can be dropped onto the asset drop zone in the card modal; a `addAsset` message is sent for each dropped file (assets handled via the extension's file picker dialog, not the webview directly — drag events trigger the extension-side file picker).
 
@@ -1014,6 +1029,7 @@ The kanban root URI is always `<workspaceRoot>/kanban`. The `kanban/` directory
 
 The kanban data directory is intentionally **not** excluded from git. The initialisation script (`initWorkspace`) adds a comment block to `.gitignore` for the index database and logs, but `kanban/` is left out so that boards and cards are version-controlled by default. Users can add `kanban/` to `.gitignore` manually if they prefer not to commit their boards.
 .          ↔ deep/nested → 2 (two hops down from root)
+
 ```
 
 The algorithm:
@@ -1246,7 +1262,7 @@ The wikilink colour defaults to the VS Code theme's `textLink.foreground` colour
 
 | Setting | Default | Description |
 |---|---|---|
-| `as-notes.wikilinkColour` | _(empty — uses theme colour)_ | Hex colour for wikilinks (e.g. `#3794ff`). Leave empty to follow the theme. |
+| `as-notes.wikilinkColour` | *(empty — uses theme colour)* | Hex colour for wikilinks (e.g. `#3794ff`). Leave empty to follow the theme. |
 
 Changing the setting takes effect immediately — no reload required. Internally, decoration types are immutable in VS Code, so changing the colour disposes the old types and creates new ones.
 
@@ -1271,6 +1287,7 @@ Parsing every line on every event is expensive for large documents. Segments are
 - **Debounced text changes:** `onDidChangeTextDocument` is debounced at 50 ms. Rapidly fired edit events are batched into a single re-parse.
 
 This ensures:
+
 - Opening a document parses once and applies decorations immediately.
 - Typing triggers at most one re-parse per 50 ms burst.
 
@@ -1630,8 +1647,8 @@ The function uses regex matching to detect the current state and return the togg
 
 1. **Done todo** — `/^(\s*)([-*])\s+\[(?:x|X)\]\s?(.*)/` → strip bullet and checkbox, return `indent + rest`
 2. **Unchecked todo** — `/^(\s*)([-*])\s+\[ \]\s?(.*)/` → replace `[ ]` with `[x]`
-3. **List item** (bullet without checkbox) — `/^(\s*)([-*])\s+(.*)/` → insert `[ ] ` after the bullet
-4. **Plain text** — everything else → prepend `- [ ] ` after leading whitespace
+3. **List item** (bullet without checkbox) — `/^(\s*)([-*])\s+(.*)/` → insert `[ ]` after the bullet
+4. **Plain text** — everything else → prepend `- [ ]` after leading whitespace
 
 Leading whitespace (indentation) is captured and preserved in all cases. Both `-` and `*` bullets are supported. Both `[x]` and `[X]` are recognised as done.
 
@@ -1882,6 +1899,7 @@ Each entry has a `kind` field:
 The webview is a separate IIFE bundle (`dist/webview/search.js`) with Tailwind CSS (`dist/webview/search.css`), built through the same PostCSS + Tailwind pipeline as the tasks view.
 
 **UI components:**
+
 - Search input with magnifying glass icon and "Go To" button
 - Dropdown list with up to 20 filtered results, absolutely positioned to overflow the panel bounds
 - Each dropdown item shows an icon (page/alias/forward), label, detail, and a "New" badge for forward references
@@ -1922,6 +1940,7 @@ The backlinks panel displays all incoming links to a target page — either the
 All backlinks are grouped by their **chain pattern** — the abstract sequence of page names from root to the target link. For example, `[[Project]] → [[Tasks]] → [[NGINX]]` is a different pattern from `[[NGINX]]` alone.
 
 Grouping logic:
+
 1. Query all links pointing to the target page's filename(s) — including alias filenames
 2. For each link, build the full chain via `buildChainForLink()` (walk `outline_parent_link_id` upward, then reverse)
 3. Compute a **pattern key**: the lowercased, `→`-joined sequence of page names (case-insensitive grouping)
@@ -1936,6 +1955,7 @@ Grouping logic:
 3. **Forward ref mode**: uses stored `lockedPageName` → `getBacklinkChainsByName(pageName)`
 
 Both `getBacklinkChains()` and `getBacklinkChainsByName()` call the private `buildBacklinkChainGroups(targetFilenames)` method which:
+
 - Queries `SELECT l.id, l.source_page_id, p.* FROM links l JOIN pages p ON l.source_page_id = p.id WHERE LOWER(l.page_filename) IN (...)` with case-insensitive filename matching
 - Builds chain for each link via `buildChainForLink(linkId)`
 - Groups by lowercased pattern key into `BacklinkChainGroup[]`
@@ -2025,6 +2045,7 @@ The default is configured via `as-notes.backlinkWrapContext` (boolean, default `
 ### Rendering
 
 Each chain group renders as a collapsible section with:
+
 - **Header**: the chain pattern displayed as clickable page name links separated by `→` arrows, with an instance count badge
 - **Instances**: each instance shows the source page title followed by the chain with per-link line numbers (e.g. `[L12]`), each clickable for navigation
 - **Context block**: below each chain instance, a multi-line context snippet (±1 surrounding lines) of the last link (the target link) is displayed in a blockquote-styled `<pre>` block. Common leading whitespace is stripped so that outliner-indented content doesn't waste horizontal space (relative indentation is preserved). The wikilink text on the relevant line is highlighted using `--vscode-textLink-foreground`. The blockquote uses `--vscode-textBlockQuote-border` for the left border and `--vscode-textBlockQuote-background` for the background fill. Context text uses `--vscode-descriptionForeground` for a muted secondary appearance.
@@ -2128,6 +2149,7 @@ Typing `/` in any markdown file (except inside front matter, inline code, or fen
 `src/SlashCommandProvider.ts` — a `vscode.CompletionItemProvider` registered on trigger character `/`.
 
 **Suppression rules** (same pattern as `WikilinkCompletionProvider`):
+
 - YAML front matter (`---` fences)
 - Fenced code blocks (` ``` ` or `~~~`)
 - Inline code spans (`` ` ``)
@@ -2160,7 +2182,7 @@ Detection for the latter two is handled by `isPositionInsideCode()` in `Completi
 | `Task: Due Date` | *(task lines only)* Replaces `/` with `""` and fires `as-notes.insertTaskDueDate` |
 | `Task: Completion Date` | *(task lines only)* Replaces `/` with `""` and fires `as-notes.insertTaskCompletionDate` |
 
-Table commands append ` (Pro)` to the label only when the user is **not** Pro licenced. Template also appends ` (Pro)` for free users. Task commands are only shown when the cursor is on a task line (`- [ ]` or `- [x]`).
+Table commands append `(Pro)` to the label only when the user is **not** Pro licenced. Template also appends `(Pro)` for free users. Task commands are only shown when the cursor is on a task line (`- [ ]` or `- [x]`).
 
 The completion range covers only the `/` character.
 
@@ -2285,12 +2307,13 @@ interface TemplateContext {
 **Clamping:** The four "Remove N" functions (`removeRowsAbove`, `removeRowsBelow`, `removeColumnsRight`, `removeColumnsLeft`) clamp the requested count to the maximum available, gracefully removing as many as possible.
 
 **Cell width rules:**
+
 - New table: default width (7 chars content area)
 - Add columns: default width for new columns
 - Add rows: widths from header row
 - Format: `max(longest cell content, default minimum)` per column
 
-**Pro gating:** All ten table commands show in the slash menu for all users but append ` (Pro)` to the label only when the user is not Pro licenced. Execution is gated via `isProLicenced()` with a warning notification for free users. `SlashCommandProvider` receives an `isProLicenced: () => boolean` callback via its constructor.
+**Pro gating:** All ten table commands show in the slash menu for all users but append `(Pro)` to the label only when the user is not Pro licenced. Execution is gated via `isProLicenced()` with a warning notification for free users. `SlashCommandProvider` receives an `isProLicenced: () => boolean` callback via its constructor.
 
 ## Pro licence
 
@@ -2327,11 +2350,13 @@ activateWithServer(key: string, context: vscode.ExtensionContext): Promise<Licen
 ```
 
 The stub:
+
 - Validates the key format locally (no network call)
 - On success, writes a stub token (`stub:<base64(key)>`) to `context.secrets` under the key `as-notes.activationToken`
 - On subsequent startups, checks the stored token before re-validating locally
 
 Three internal helpers are clearly marked for replacement:
+
 - `_callServer(key)` — replace with the real HTTP call
 - `_buildToken(key)` — replace with storage of the server-returned signed token
 - `_verifyToken(token, key)` — replace with Ed25519/HMAC signature verification against the baked-in public key
@@ -2420,6 +2445,7 @@ ensurePreCommitHook(workspaceRoot: string): HookResult
 ```
 
 `ensurePreCommitHook()` is **idempotent** and **self-healing**:
+
 - `no-git` — `.git/hooks/` directory does not exist (not a git repo)
 - `created` — no pre-commit hook existed; created with `#!/bin/sh` + block
 - `appended` — hook existed but lacked the marker; block appended
@@ -2431,6 +2457,7 @@ ensurePreCommitHook(workspaceRoot: string): HookResult
 The hook file is made executable via `fs.chmodSync(hookPath, 0o755)` (wrapped in try/catch — no-op on Windows without Git Bash, but the hook still runs in Git Bash environments).
 
 `ensurePreCommitHook()` is called in three places in `extension.ts`:
+
 1. `initWorkspace()` — after creating `.asnotes/`
 2. `rebuildIndex()` — at the start of the rebuild
 3. `startPeriodicScan()` setInterval callback — each periodic scan tick
@@ -2493,6 +2520,7 @@ to `.vscode/settings.json` at workspace scope. `${fileName}` is a built-in VS Co
 | `as-notes.assetPath` | `assets/images` | Workspace-relative folder where dropped/pasted files are saved |
 
 **Trigger points** (all in `extension.ts`):
+
 1. `enterFullMode()` — on activation when `.asnotes/` is found
 2. `initWorkspace` command — when user initialises a new workspace
 3. `rebuildIndex` command — re-applies in case settings were modified externally
@@ -2526,7 +2554,7 @@ Both use the same regex pattern. If the sanitisation rules change, both must be
 
 ## Outliner mode
 
-Outliner mode (`as-notes.outlinerMode` setting) turns the markdown editor into a bullet-first outliner. It only affects lines beginning with `- ` (hyphen-space) — all other lines retain normal editor behaviour.
+Outliner mode (`as-notes.outlinerMode` setting) turns the markdown editor into a bullet-first outliner. It only affects lines beginning with `-` (hyphen-space) — all other lines retain normal editor behaviour.
 
 ### OutlinerService
 
@@ -2537,7 +2565,7 @@ Outliner mode (`as-notes.outlinerMode` setting) turns the markdown editor into a
 | Function | Purpose |
 |---|---|
 | `isOnBulletLine(lineText)` | Returns `true` for lines matching `/^\s*- /` |
-| `getOutlinerEnterInsert(lineText)` | Returns the `\n{indent}- ` or `\n{indent}- [ ] ` string to insert on Enter |
+| `getOutlinerEnterInsert(lineText)` | Returns the `\n{indent}-` or `\n{indent}- [ ]` string to insert on Enter |
 | `isCodeFenceOpen(lineText)` | Returns `true` when a bullet line ends with `` ``` `` (optionally + language) |
 | `getCodeFenceEnterInsert(lineText)` | Returns the code block skeleton to insert on Enter (indented +2 past bullet) |
 | `isStandaloneCodeFenceOpen(lineText)` | Returns `true` for non-bullet lines matching opening `` ``` `` (optionally + language) |
@@ -2564,6 +2592,7 @@ This combination allows keybindings to fire only when in outliner mode AND on a
 Keybinding: `Enter` when `editorLangId == markdown && as-notes.outlinerMode && as-notes.onBulletLine && !suggestWidgetVisible && editorHasSelection == false && !inlineSuggestionVisible`.
 
 Command `as-notes.outlinerEnter` for each cursor (in priority order):
+
 1. **Bullet code fence open** — `isCodeFenceOpen` returns `true`: inserts code block skeleton indented +2 past bullet (see below).
 2. **Bullet line** — deletes from cursor to end of line, inserts `getOutlinerEnterInsert(lineText)`. Text after cursor is pushed to the new bullet.
 
@@ -2628,22 +2657,24 @@ On non-bullet lines Tab retains normal VS Code behaviour with no extra logic.
 Keybinding: `Ctrl+V` / `Cmd+V` when `editorLangId == markdown && as-notes.outlinerMode && as-notes.onBulletLine && !editorReadonly`.
 
 Command `as-notes.outlinerPaste`:
+
 1. Reads clipboard via `vscode.env.clipboard.readText()`.
 2. Calls `formatOutlinerPaste(lineText, cursorCharacter, clipboardText)`.
 3. If result is `null` (single-line paste or all-empty lines), falls through to `editor.action.clipboardPasteAction`.
 4. Otherwise, replaces the entire current line with the formatted bullets.
 
 **`formatOutlinerPaste` rules:**
+
 - CRLF normalised to LF. Empty/whitespace-only lines stripped. Each remaining line trimmed.
-- Plain bullet: each line gets `{indent}- ` prefix.
-- Unchecked todo: each line gets `{indent}- [ ] ` prefix.
-- Done todo: first line keeps `{indent}- [x] `, subsequent lines get `{indent}- [ ] `.
+- Plain bullet: each line gets `{indent}-` prefix.
+- Unchecked todo: each line gets `{indent}- [ ]` prefix.
+- Done todo: first line keeps `{indent}- [x]`, subsequent lines get `{indent}- [ ]`.
 - Text before cursor on the current line is preserved; text after cursor is appended to the last pasted line.
 - Single-line clipboard text: no conversion (returns `null`).
 
 ### Todo toggle in outliner mode
 
-When `as-notes.outlinerMode` is enabled and the line `isOnBulletLine`, the `as-notes.toggleTodo` command uses `toggleOutlinerTodoLine` instead of the default `toggleTodoLine`. The outliner cycle preserves the `- ` prefix:
+When `as-notes.outlinerMode` is enabled and the line `isOnBulletLine`, the `as-notes.toggleTodo` command uses `toggleOutlinerTodoLine` instead of the default `toggleTodoLine`. The outliner cycle preserves the `-` prefix:
 
 | State | Default toggle result | Outliner toggle result |
 |---|---|---|
@@ -2673,7 +2704,7 @@ When `as-notes.outlinerMode` is enabled and the line `isOnBulletLine`, the `as-n
    - Registers the `as-notes.navigateWikilink`, `as-notes.toggleTodo`, `as-notes.toggleTaskAtLine`, `as-notes.toggleTaskFromPanel`, `as-notes.navigateToTask`, `as-notes.showBacklinks`, `as-notes.openDailyJournal`, `as-notes.renameJournalFiles`, task hashtag commands (`as-notes.insertTaskHashtag`, `as-notes.insertTaskDueDate`, `as-notes.insertTaskCompletionDate`), and all eight encryption commands
    - Sets up index update triggers (save, file events, editor switch)
    - Starts the periodic scanner
-5. **Passive mode** (no `.asnotes/`): status bar only, no providers, context key cleared. Passive-mode command stubs remain active.
+6. **Passive mode** (no `.asnotes/`): status bar only, no providers, context key cleared. Passive-mode command stubs remain active.
 
 All full-mode registrations are tracked in `fullModeDisposables[]` and pushed to `context.subscriptions`. The `deactivate()` function persists the database and cleans up.
 
diff --git a/assets/images/as-notes-editor-screenshot.png b/assets/images/as-notes-editor-screenshot.png
new file mode 100644
index 0000000..090288a
Binary files /dev/null and b/assets/images/as-notes-editor-screenshot.png differ
diff --git a/common/src/FrontMatterService.ts b/common/src/FrontMatterService.ts
new file mode 100644
index 0000000..51d3644
--- /dev/null
+++ b/common/src/FrontMatterService.ts
@@ -0,0 +1,373 @@
+/**
+ * Lightweight YAML front matter parser for extracting metadata from markdown files.
+ *
+ * Supports the standard YAML front matter format delimited by `---` fences at
+ * the start of the file. Extracts the `aliases` field and general front matter
+ * fields used for publishing (public, title, order, description, layout, assets,
+ * retina, draft, date).
+ *
+ * Supports two alias formats:
+ *
+ * List style:
+ * ```yaml
+ * ---
+ * aliases:
+ *   - Alias One
+ *   - Alias Two
+ * ---
+ * ```
+ *
+ * Inline array style:
+ * ```yaml
+ * ---
+ * aliases: [Alias One, Alias Two]
+ * ---
+ * ```
+ *
+ * Alias values are plain strings -- any accidental `[[` or `]]` bracket syntax
+ * is stripped automatically.
+ */
+
+/** Typed front matter fields for publishing and metadata. */
+export interface FrontMatterFields {
+    public?: boolean;
+    title?: string;
+    order?: number;
+    description?: string;
+    layout?: string;
+    assets?: boolean;
+    retina?: boolean;
+    draft?: boolean;
+    date?: string;
+    aliases?: string[];
+}
+
+export class FrontMatterService {
+
+    /**
+     * Extract the raw front matter block from markdown content.
+     * Returns the text between the first two `---` lines, or null if
+     * no valid front matter block is found.
+     *
+     * Front matter must start at the very beginning of the file (line 0).
+     */
+    extractFrontMatter(content: string): string | null {
+        const lines = content.split(/\r?\n/);
+        if (lines.length === 0 || lines[0].trim() !== '---') {
+            return null;
+        }
+
+        // Find the closing ---
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === '---') {
+                // Return the block between the fences (exclusive of the --- lines)
+                return lines.slice(1, i).join('\n');
+            }
+        }
+
+        return null; // No closing fence found
+    }
+
+    /**
+     * Strip the front matter block from markdown content.
+     * Returns the content after the closing `---` fence.
+     * If no front matter exists, returns the original content unchanged.
+     */
+    stripFrontMatter(content: string): string {
+        const lines = content.split(/\r?\n/);
+        if (lines.length === 0 || lines[0].trim() !== '---') {
+            return content;
+        }
+
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === '---') {
+                // Return everything after the closing fence
+                return lines.slice(i + 1).join('\n');
+            }
+        }
+
+        return content; // No closing fence found, return as-is
+    }
+
+    /**
+     * Parse general front matter fields from markdown content.
+     * Returns a typed object with known publishing/metadata fields.
+     * Unknown fields are ignored.
+     */
+    parseFrontMatterFields(content: string): FrontMatterFields {
+        const frontMatter = this.extractFrontMatter(content);
+        if (!frontMatter) {
+            return {};
+        }
+
+        const fields: FrontMatterFields = {};
+        const lines = frontMatter.split(/\r?\n/);
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+
+            // Match top-level key: value pairs (not indented list items)
+            const kvMatch = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
+            if (!kvMatch) {
+                continue;
+            }
+
+            const key = kvMatch[1].toLowerCase();
+            const rawValue = kvMatch[2].trim();
+
+            switch (key) {
+                case 'public':
+                    fields.public = this.parseBooleanValue(rawValue);
+                    break;
+                case 'title':
+                    fields.title = this.parseStringValue(rawValue);
+                    break;
+                case 'order':
+                    fields.order = this.parseNumberValue(rawValue);
+                    break;
+                case 'description':
+                    fields.description = this.parseStringValue(rawValue);
+                    break;
+                case 'layout':
+                    fields.layout = this.parseStringValue(rawValue);
+                    break;
+                case 'assets':
+                    fields.assets = this.parseBooleanValue(rawValue);
+                    break;
+                case 'retina':
+                    fields.retina = this.parseBooleanValue(rawValue);
+                    break;
+                case 'draft':
+                    fields.draft = this.parseBooleanValue(rawValue);
+                    break;
+                case 'date':
+                    fields.date = this.parseStringValue(rawValue);
+                    break;
+                case 'aliases':
+                    fields.aliases = this.parseAliasesFromLine(rawValue, lines, i);
+                    break;
+            }
+        }
+
+        return fields;
+    }
+
+    /**
+     * Parse aliases from markdown file content.
+     *
+     * Extracts the `aliases:` field from the YAML front matter and returns
+     * an array of alias name strings. Returns an empty array if no front
+     * matter exists or no aliases are defined.
+     *
+     * Strips any accidental `[[` / `]]` wikilink brackets from alias values.
+     */
+    parseAliases(content: string): string[] {
+        const frontMatter = this.extractFrontMatter(content);
+        if (!frontMatter) {
+            return [];
+        }
+
+        return this.parseAliasesFromFrontMatter(frontMatter);
+    }
+
+    /**
+     * Parse the aliases field from a front matter block (without the --- fences).
+     */
+    private parseAliasesFromFrontMatter(frontMatter: string): string[] {
+        const lines = frontMatter.split(/\r?\n/);
+
+        // Find the aliases: line
+        let aliasLineIndex = -1;
+        let aliasLineContent = '';
+        for (let i = 0; i < lines.length; i++) {
+            const match = lines[i].match(/^aliases\s*:\s*(.*)/);
+            if (match) {
+                aliasLineIndex = i;
+                aliasLineContent = match[1].trim();
+                break;
+            }
+        }
+
+        if (aliasLineIndex === -1) {
+            return [];
+        }
+
+        return this.parseAliasesFromLine(aliasLineContent, lines, aliasLineIndex);
+    }
+
+    /**
+     * Parse aliases from the value portion of an aliases: line + subsequent lines.
+     */
+    private parseAliasesFromLine(value: string, lines: string[], lineIndex: number): string[] {
+        // Check for inline array: aliases: [Alias One, Alias Two]
+        if (value.startsWith('[')) {
+            return this.parseInlineArray(value);
+        }
+
+        // Check for a single inline value: aliases: Some Alias
+        if (value.length > 0) {
+            const cleaned = this.cleanAliasValue(value);
+            return cleaned ? [cleaned] : [];
+        }
+
+        // List style: collect subsequent indented `- item` lines
+        return this.parseListItems(lines, lineIndex + 1);
+    }
+
+    /**
+     * Parse an inline array like `[Alias One, Alias Two]`.
+     */
+    private parseInlineArray(value: string): string[] {
+        // Remove surrounding brackets
+        const inner = value.replace(/^\[/, '').replace(/\]$/, '');
+        if (inner.trim().length === 0) {
+            return [];
+        }
+
+        return inner
+            .split(',')
+            .map(item => this.cleanAliasValue(item.trim()))
+            .filter((item): item is string => item !== null && item.length > 0);
+    }
+
+    /**
+     * Parse list-style items starting from the given line index.
+     * Collects lines matching `  - value` until a non-list line is hit.
+     */
+    private parseListItems(lines: string[], startIndex: number): string[] {
+        const aliases: string[] = [];
+
+        for (let i = startIndex; i < lines.length; i++) {
+            const match = lines[i].match(/^\s+-\s+(.*)/);
+            if (!match) {
+                break; // End of list
+            }
+            const cleaned = this.cleanAliasValue(match[1].trim());
+            if (cleaned && cleaned.length > 0) {
+                aliases.push(cleaned);
+            }
+        }
+
+        return aliases;
+    }
+
+    /**
+     * Clean an alias value by stripping accidental wikilink brackets and
+     * surrounding quotes.
+     *
+     * @returns The cleaned string, or null if the result is empty.
+     */
+    private cleanAliasValue(value: string): string | null {
+        // Strip surrounding quotes (single or double)
+        let cleaned = value.replace(/^["']|["']$/g, '');
+        // Strip any [[ or ]] bracket syntax
+        cleaned = cleaned.replace(/\[\[|\]\]/g, '');
+        cleaned = cleaned.trim();
+        return cleaned.length > 0 ? cleaned : null;
+    }
+
+    /**
+     * Parse a boolean value from a YAML string.
+     * Recognises `true`, `false`, `yes`, `no` (case-insensitive).
+     */
+    private parseBooleanValue(value: string): boolean | undefined {
+        const lower = value.toLowerCase();
+        if (lower === 'true' || lower === 'yes') {
+            return true;
+        }
+        if (lower === 'false' || lower === 'no') {
+            return false;
+        }
+        return undefined;
+    }
+
+    /**
+     * Parse a string value, stripping surrounding quotes.
+     */
+    private parseStringValue(value: string): string | undefined {
+        if (value.length === 0) {
+            return undefined;
+        }
+        // Strip surrounding quotes (single or double)
+        return value.replace(/^["']|["']$/g, '').trim() || undefined;
+    }
+
+    /**
+     * Parse a numeric value.
+     */
+    private parseNumberValue(value: string): number | undefined {
+        const num = Number(value);
+        return Number.isFinite(num) ? num : undefined;
+    }
+
+    /**
+     * Update a specific alias in the front matter of a markdown file.
+     * Returns the modified file content, or null if the alias was not found.
+     *
+     * Handles both list-style and inline array formats.
+     */
+    updateAlias(content: string, oldAlias: string, newAlias: string): string | null {
+        const lines = content.split(/\r?\n/);
+        if (lines.length === 0 || lines[0].trim() !== '---') {
+            return null;
+        }
+
+        // Find closing fence
+        let closingIndex = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === '---') {
+                closingIndex = i;
+                break;
+            }
+        }
+        if (closingIndex === -1) {
+            return null;
+        }
+
+        // Find the aliases: line within the front matter
+        let aliasLineIndex = -1;
+        for (let i = 1; i < closingIndex; i++) {
+            if (lines[i].match(/^aliases\s*:/)) {
+                aliasLineIndex = i;
+                break;
+            }
+        }
+        if (aliasLineIndex === -1) {
+            return null;
+        }
+
+        const aliasLine = lines[aliasLineIndex];
+        const afterColon = aliasLine.replace(/^aliases\s*:\s*/, '').trim();
+
+        // Inline array format: aliases: [Alias One, Alias Two]
+        if (afterColon.startsWith('[')) {
+            const updated = aliasLine.replace(oldAlias, newAlias);
+            if (updated === aliasLine) {
+                return null; // oldAlias not found
+            }
+            lines[aliasLineIndex] = updated;
+            return lines.join('\n');
+        }
+
+        // Single inline value: aliases: Some Alias
+        if (afterColon.length > 0 && this.cleanAliasValue(afterColon) === oldAlias) {
+            lines[aliasLineIndex] = aliasLine.replace(oldAlias, newAlias);
+            return lines.join('\n');
+        }
+
+        // List style: find the matching `- oldAlias` line
+        for (let i = aliasLineIndex + 1; i < closingIndex; i++) {
+            const match = lines[i].match(/^(\s+-\s+)(.*)/);
+            if (!match) {
+                break;
+            }
+            const cleaned = this.cleanAliasValue(match[2].trim());
+            if (cleaned === oldAlias) {
+                lines[i] = match[1] + newAlias;
+                return lines.join('\n');
+            }
+        }
+
+        return null; // alias not found
+    }
+}
diff --git a/common/src/index.ts b/common/src/index.ts
index 1f486c4..170bc72 100644
--- a/common/src/index.ts
+++ b/common/src/index.ts
@@ -1,3 +1,4 @@
 export { Wikilink } from './Wikilink.js';
 export { WikilinkService, type IWikilinkService, type LinkSegment } from './WikilinkService.js';
 export { wikilinkPlugin, stripBrackets, type WikilinkResolverFn } from './MarkdownItWikilinkPlugin.js';
+export { FrontMatterService, type FrontMatterFields } from './FrontMatterService.js';
diff --git a/common/test/FrontMatterService.test.ts b/common/test/FrontMatterService.test.ts
new file mode 100644
index 0000000..fa014c0
--- /dev/null
+++ b/common/test/FrontMatterService.test.ts
@@ -0,0 +1,305 @@
+import { describe, it, expect } from 'vitest';
+import { FrontMatterService } from '../src/FrontMatterService.js';
+
+describe('FrontMatterService — extractFrontMatter', () => {
+    const service = new FrontMatterService();
+
+    it('should extract front matter between --- fences', () => {
+        const content = '---\ntitle: My Page\naliases: [A, B]\n---\n\n# Body';
+        expect(service.extractFrontMatter(content)).toBe('title: My Page\naliases: [A, B]');
+    });
+
+    it('should return null when no front matter exists', () => {
+        const content = '# Just a heading\n\nSome text.';
+        expect(service.extractFrontMatter(content)).toBeNull();
+    });
+
+    it('should return null when file does not start with ---', () => {
+        const content = 'Some text\n---\naliases: [A]\n---';
+        expect(service.extractFrontMatter(content)).toBeNull();
+    });
+
+    it('should return null when closing fence is missing', () => {
+        const content = '---\naliases: [A, B]\n';
+        expect(service.extractFrontMatter(content)).toBeNull();
+    });
+
+    it('should handle empty front matter', () => {
+        const content = '---\n---\n\nBody text.';
+        expect(service.extractFrontMatter(content)).toBe('');
+    });
+
+    it('should handle Windows line endings', () => {
+        const content = '---\r\ntitle: Test\r\n---\r\n\r\nBody';
+        expect(service.extractFrontMatter(content)).toBe('title: Test');
+    });
+});
+
+describe('FrontMatterService — parseAliases', () => {
+    const service = new FrontMatterService();
+
+    it('should parse list-style aliases', () => {
+        const content = '---\naliases:\n  - Alias One\n  - Alias Two\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['Alias One', 'Alias Two']);
+    });
+
+    it('should parse inline array aliases', () => {
+        const content = '---\naliases: [Alias One, Alias Two]\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['Alias One', 'Alias Two']);
+    });
+
+    it('should parse single inline alias', () => {
+        const content = '---\naliases: My Alias\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['My Alias']);
+    });
+
+    it('should return empty array when no front matter', () => {
+        const content = '# Just a page\n\nNo front matter here.';
+        expect(service.parseAliases(content)).toEqual([]);
+    });
+
+    it('should return empty array when no aliases field', () => {
+        const content = '---\ntitle: My Page\ntags: [foo]\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual([]);
+    });
+
+    it('should strip accidental [[ and ]] brackets', () => {
+        const content = '---\naliases:\n  - "[[Bracketed Alias]]"\n  - Normal Alias\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['Bracketed Alias', 'Normal Alias']);
+    });
+
+    it('should strip brackets from inline array values', () => {
+        const content = '---\naliases: [[[Alias A]], Alias B]\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['Alias A', 'Alias B']);
+    });
+
+    it('should handle empty aliases list', () => {
+        const content = '---\naliases:\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual([]);
+    });
+
+    it('should handle empty inline array', () => {
+        const content = '---\naliases: []\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual([]);
+    });
+
+    it('should strip surrounding quotes from alias values', () => {
+        const content = '---\naliases:\n  - "Quoted Alias"\n  - \'Single Quoted\'\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['Quoted Alias', 'Single Quoted']);
+    });
+
+    it('should handle aliases with mixed whitespace', () => {
+        const content = '---\naliases:   [  Alias A  ,  Alias B  ]\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['Alias A', 'Alias B']);
+    });
+
+    it('should handle aliases field with other fields around it', () => {
+        const content = '---\ntitle: My Page\naliases:\n  - A1\n  - A2\ntags: [foo]\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['A1', 'A2']);
+    });
+
+    it('should stop list parsing at non-list line', () => {
+        const content = '---\naliases:\n  - A1\n  - A2\ntitle: Next Field\n---\n\n# Page';
+        expect(service.parseAliases(content)).toEqual(['A1', 'A2']);
+    });
+});
+
+describe('FrontMatterService — updateAlias', () => {
+    const service = new FrontMatterService();
+
+    it('should update an alias in list format', () => {
+        const content = '---\naliases:\n  - Old Alias\n  - Other\n---\n\n# Page';
+        const result = service.updateAlias(content, 'Old Alias', 'New Alias');
+        expect(result).toBe('---\naliases:\n  - New Alias\n  - Other\n---\n\n# Page');
+    });
+
+    it('should update an alias in inline array format', () => {
+        const content = '---\naliases: [Old Alias, Other]\n---\n\n# Page';
+        const result = service.updateAlias(content, 'Old Alias', 'New Alias');
+        expect(result).toBe('---\naliases: [New Alias, Other]\n---\n\n# Page');
+    });
+
+    it('should update a single inline alias', () => {
+        const content = '---\naliases: Old Alias\n---\n\n# Page';
+        const result = service.updateAlias(content, 'Old Alias', 'New Alias');
+        expect(result).toBe('---\naliases: New Alias\n---\n\n# Page');
+    });
+
+    it('should return null when alias not found', () => {
+        const content = '---\naliases:\n  - Some Alias\n---\n\n# Page';
+        const result = service.updateAlias(content, 'Nonexistent', 'New');
+        expect(result).toBeNull();
+    });
+
+    it('should return null when no front matter', () => {
+        const content = '# Just a page';
+        const result = service.updateAlias(content, 'A', 'B');
+        expect(result).toBeNull();
+    });
+
+    it('should return null when no aliases field', () => {
+        const content = '---\ntitle: My Page\n---\n\n# Page';
+        const result = service.updateAlias(content, 'A', 'B');
+        expect(result).toBeNull();
+    });
+
+    it('should preserve surrounding content', () => {
+        const content = '---\ntitle: My Page\naliases:\n  - Target\ntags: [foo]\n---\n\n# Body text here\n\nMore content.';
+        const result = service.updateAlias(content, 'Target', 'Updated');
+        expect(result).toBe('---\ntitle: My Page\naliases:\n  - Updated\ntags: [foo]\n---\n\n# Body text here\n\nMore content.');
+    });
+});
+
+describe('FrontMatterService — stripFrontMatter', () => {
+    const service = new FrontMatterService();
+
+    it('should strip front matter and return remaining content', () => {
+        const content = '---\ntitle: My Page\npublic: true\n---\n\n# Hello\n\nBody text.';
+        expect(service.stripFrontMatter(content)).toBe('\n# Hello\n\nBody text.');
+    });
+
+    it('should return original content when no front matter', () => {
+        const content = '# Just a heading\n\nSome text.';
+        expect(service.stripFrontMatter(content)).toBe(content);
+    });
+
+    it('should return original content when closing fence is missing', () => {
+        const content = '---\ntitle: My Page\n';
+        expect(service.stripFrontMatter(content)).toBe(content);
+    });
+
+    it('should handle empty front matter', () => {
+        const content = '---\n---\n\nBody text.';
+        expect(service.stripFrontMatter(content)).toBe('\nBody text.');
+    });
+
+    it('should handle Windows line endings', () => {
+        const content = '---\r\ntitle: Test\r\n---\r\n\r\nBody';
+        // Line endings are normalised to \n during split/join
+        expect(service.stripFrontMatter(content)).toBe('\nBody');
+    });
+
+    it('should handle content immediately after closing fence', () => {
+        const content = '---\ntitle: Test\n---\n# Heading';
+        expect(service.stripFrontMatter(content)).toBe('# Heading');
+    });
+});
+
+describe('FrontMatterService — parseFrontMatterFields', () => {
+    const service = new FrontMatterService();
+
+    it('should parse public: true', () => {
+        const content = '---\npublic: true\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).public).toBe(true);
+    });
+
+    it('should parse public: false', () => {
+        const content = '---\npublic: false\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).public).toBe(false);
+    });
+
+    it('should parse public: yes/no', () => {
+        expect(service.parseFrontMatterFields('---\npublic: yes\n---').public).toBe(true);
+        expect(service.parseFrontMatterFields('---\npublic: no\n---').public).toBe(false);
+    });
+
+    it('should parse title field', () => {
+        const content = '---\ntitle: My Custom Title\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).title).toBe('My Custom Title');
+    });
+
+    it('should parse quoted title field', () => {
+        const content = '---\ntitle: "My Quoted Title"\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).title).toBe('My Quoted Title');
+    });
+
+    it('should parse order field as number', () => {
+        const content = '---\norder: 5\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).order).toBe(5);
+    });
+
+    it('should parse negative order', () => {
+        const content = '---\norder: -1\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).order).toBe(-1);
+    });
+
+    it('should return undefined for non-numeric order', () => {
+        const content = '---\norder: abc\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).order).toBeUndefined();
+    });
+
+    it('should parse description field', () => {
+        const content = '---\ndescription: A brief description of the page\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).description).toBe('A brief description of the page');
+    });
+
+    it('should parse layout field', () => {
+        const content = '---\nlayout: blog\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).layout).toBe('blog');
+    });
+
+    it('should parse assets: true', () => {
+        const content = '---\nassets: true\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).assets).toBe(true);
+    });
+
+    it('should parse retina: true', () => {
+        const content = '---\nretina: true\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).retina).toBe(true);
+    });
+
+    it('should parse draft: true', () => {
+        const content = '---\ndraft: true\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).draft).toBe(true);
+    });
+
+    it('should parse date field', () => {
+        const content = '---\ndate: 2026-03-23\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).date).toBe('2026-03-23');
+    });
+
+    it('should parse aliases via parseFrontMatterFields', () => {
+        const content = '---\naliases: [Alias A, Alias B]\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).aliases).toEqual(['Alias A', 'Alias B']);
+    });
+
+    it('should parse aliases list style via parseFrontMatterFields', () => {
+        const content = '---\naliases:\n  - Alias A\n  - Alias B\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content).aliases).toEqual(['Alias A', 'Alias B']);
+    });
+
+    it('should parse multiple fields together', () => {
+        const content = '---\npublic: true\ntitle: My Page\norder: 3\ndescription: A description\nlayout: docs\ndate: 2026-01-15\n---\n\n# Page';
+        const fields = service.parseFrontMatterFields(content);
+        expect(fields.public).toBe(true);
+        expect(fields.title).toBe('My Page');
+        expect(fields.order).toBe(3);
+        expect(fields.description).toBe('A description');
+        expect(fields.layout).toBe('docs');
+        expect(fields.date).toBe('2026-01-15');
+    });
+
+    it('should return empty object when no front matter', () => {
+        const content = '# Just a page\n\nNo front matter.';
+        expect(service.parseFrontMatterFields(content)).toEqual({});
+    });
+
+    it('should return empty object for empty front matter', () => {
+        const content = '---\n---\n\n# Page';
+        expect(service.parseFrontMatterFields(content)).toEqual({});
+    });
+
+    it('should be case-insensitive for field names', () => {
+        const content = '---\nPublic: true\nTitle: My Title\n---\n\n# Page';
+        const fields = service.parseFrontMatterFields(content);
+        expect(fields.public).toBe(true);
+        expect(fields.title).toBe('My Title');
+    });
+
+    it('should handle boolean values case-insensitively', () => {
+        const content = '---\npublic: TRUE\nassets: False\n---\n\n# Page';
+        const fields = service.parseFrontMatterFields(content);
+        expect(fields.public).toBe(true);
+        expect(fields.assets).toBe(false);
+    });
+});
diff --git a/docs-src/.gitignore b/docs-src/.gitignore
new file mode 100644
index 0000000..abe7460
--- /dev/null
+++ b/docs-src/.gitignore
@@ -0,0 +1,3 @@
+
+.asnotes/
+.asnotesignore
\ No newline at end of file
diff --git a/docs-src/.vscode/settings.json b/docs-src/.vscode/settings.json
new file mode 100644
index 0000000..a0446e0
--- /dev/null
+++ b/docs-src/.vscode/settings.json
@@ -0,0 +1,5 @@
+{
+    "markdown.copyFiles.destination": {
+        "**/*.md": "/assets/images/${fileName}"
+    }
+}
\ No newline at end of file
diff --git a/docs-src/asnotes-publish.blog.json b/docs-src/asnotes-publish.blog.json
new file mode 100644
index 0000000..8d4f763
--- /dev/null
+++ b/docs-src/asnotes-publish.blog.json
@@ -0,0 +1,16 @@
+{
+    "inputDir": "./blog",
+    "defaultPublic": true,
+    "defaultAssets": true,
+    "layout": "blog",
+    "layouts": "./asnotes-publish.layouts.blog",
+    "includes": "./asnotes-publish.includes.blog",
+    "theme": "dark",
+    "themes": "./asnotes-publish.themes.blog",
+    "baseUrl": "",
+    "retina": false,
+    "includeDrafts": false,
+    "stylesheets": [],
+    "exclude": [],
+    "outputDir": "./blog-publish"
+}
diff --git a/docs-src/asnotes-publish.includes.blog/footer.html b/docs-src/asnotes-publish.includes.blog/footer.html
new file mode 100644
index 0000000..1fdee5d
--- /dev/null
+++ b/docs-src/asnotes-publish.includes.blog/footer.html
@@ -0,0 +1,3 @@
+<div class="site-footer">
+    <p>&copy; 2026 Built with <a href="https://www.asnotes.io">AS Notes</a> by <a href="https://www.appsoftware.com">App Software Ltd</a></p>
+</div>
diff --git a/docs-src/asnotes-publish.includes.blog/header.html b/docs-src/asnotes-publish.includes.blog/header.html
new file mode 100644
index 0000000..8025a14
--- /dev/null
+++ b/docs-src/asnotes-publish.includes.blog/header.html
@@ -0,0 +1,5 @@
+<div class="site-header">
+    <a class="site-title" href="{{base-url}}/">
+        <svg class="site-logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 191.82 166.13" width="24" height="21"><path fill="currentColor" fill-rule="evenodd" d="M67.09,132.92,47.93,166.13H9.59L0,149.52,86.33,0H105.5L19.17,149.52H38.34l19.17-33.2h76.8l9.59,16.6Zm48-83.12,9.65,16.71H143.9L115.08,16.6q-24,41.57-48,83.12H143.9q14.37,24.9,28.76,49.8h-96l-9.59,16.61H182.24l9.58-16.61-38.34-66.4H96C95.85,82.9,113.39,52.73,115.08,49.8Z"/></svg>
+    </a>
+</div>
diff --git a/docs-src/asnotes-publish.includes.notes/footer.html b/docs-src/asnotes-publish.includes.notes/footer.html
new file mode 100644
index 0000000..1fdee5d
--- /dev/null
+++ b/docs-src/asnotes-publish.includes.notes/footer.html
@@ -0,0 +1,3 @@
+<div class="site-footer">
+    <p>&copy; 2026 Built with <a href="https://www.asnotes.io">AS Notes</a> by <a href="https://www.appsoftware.com">App Software Ltd</a></p>
+</div>
diff --git a/docs-src/asnotes-publish.includes.notes/header.html b/docs-src/asnotes-publish.includes.notes/header.html
new file mode 100644
index 0000000..8025a14
--- /dev/null
+++ b/docs-src/asnotes-publish.includes.notes/header.html
@@ -0,0 +1,5 @@
+<div class="site-header">
+    <a class="site-title" href="{{base-url}}/">
+        <svg class="site-logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 191.82 166.13" width="24" height="21"><path fill="currentColor" fill-rule="evenodd" d="M67.09,132.92,47.93,166.13H9.59L0,149.52,86.33,0H105.5L19.17,149.52H38.34l19.17-33.2h76.8l9.59,16.6Zm48-83.12,9.65,16.71H143.9L115.08,16.6q-24,41.57-48,83.12H143.9q14.37,24.9,28.76,49.8h-96l-9.59,16.61H182.24l9.58-16.61-38.34-66.4H96C95.85,82.9,113.39,52.73,115.08,49.8Z"/></svg>
+    </a>
+</div>
diff --git a/docs-src/asnotes-publish.layouts.blog/blog.html b/docs-src/asnotes-publish.layouts.blog/blog.html
new file mode 100644
index 0000000..8bf971d
--- /dev/null
+++ b/docs-src/asnotes-publish.layouts.blog/blog.html
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="blog">
+{{header}}    <article class="blog-post">
+{{date}}{{toc}}
+{{content}}
+    </article>
+{{nav}}{{footer}}</body>
+</html>
diff --git a/docs-src/asnotes-publish.layouts.blog/docs.html b/docs-src/asnotes-publish.layouts.blog/docs.html
new file mode 100644
index 0000000..4ad00e2
--- /dev/null
+++ b/docs-src/asnotes-publish.layouts.blog/docs.html
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="docs">
+{{header}}{{nav}}
+    <article class="markdown-body">
+{{toc}}
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
diff --git a/docs-src/asnotes-publish.layouts.blog/minimal.html b/docs-src/asnotes-publish.layouts.blog/minimal.html
new file mode 100644
index 0000000..0d9e85c
--- /dev/null
+++ b/docs-src/asnotes-publish.layouts.blog/minimal.html
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="minimal">
+{{header}}    <article>
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
diff --git a/docs-src/asnotes-publish.layouts.notes/blog.html b/docs-src/asnotes-publish.layouts.notes/blog.html
new file mode 100644
index 0000000..8bf971d
--- /dev/null
+++ b/docs-src/asnotes-publish.layouts.notes/blog.html
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="blog">
+{{header}}    <article class="blog-post">
+{{date}}{{toc}}
+{{content}}
+    </article>
+{{nav}}{{footer}}</body>
+</html>
diff --git a/docs-src/asnotes-publish.layouts.notes/docs.html b/docs-src/asnotes-publish.layouts.notes/docs.html
new file mode 100644
index 0000000..4ad00e2
--- /dev/null
+++ b/docs-src/asnotes-publish.layouts.notes/docs.html
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="docs">
+{{header}}{{nav}}
+    <article class="markdown-body">
+{{toc}}
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
diff --git a/docs-src/asnotes-publish.layouts.notes/minimal.html b/docs-src/asnotes-publish.layouts.notes/minimal.html
new file mode 100644
index 0000000..0d9e85c
--- /dev/null
+++ b/docs-src/asnotes-publish.layouts.notes/minimal.html
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="minimal">
+{{header}}    <article>
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
diff --git a/docs-src/asnotes-publish.notes.json b/docs-src/asnotes-publish.notes.json
new file mode 100644
index 0000000..73ac314
--- /dev/null
+++ b/docs-src/asnotes-publish.notes.json
@@ -0,0 +1,16 @@
+{
+    "inputDir": "./notes",
+    "defaultPublic": true,
+    "defaultAssets": true,
+    "layout": "docs",
+    "layouts": "./asnotes-publish.layouts.notes",
+    "includes": "./asnotes-publish.includes.notes",
+    "theme": "dark",
+    "themes": "./asnotes-publish.themes.notes",
+    "baseUrl": "",
+    "retina": false,
+    "includeDrafts": false,
+    "stylesheets": [],
+    "exclude": [],
+    "outputDir": "./notes-publish"
+}
diff --git a/docs-src/asnotes-publish.themes.blog/dark.css b/docs-src/asnotes-publish.themes.blog/dark.css
new file mode 100644
index 0000000..e550f68
--- /dev/null
+++ b/docs-src/asnotes-publish.themes.blog/dark.css
@@ -0,0 +1,285 @@
+/* AS Notes dark theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #c9d1d9;
+    background: #0d1117;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #161b22;
+    border-bottom: 1px solid #30363d;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #c9d1d9;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #58a6ff;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #30363d;
+    background: #161b22;
+    font-size: 0.85rem;
+    color: #8b949e;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #58a6ff;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #161b22;
+    border-right: 1px solid #30363d;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #c9d1d9;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #1f2937;
+}
+
+.site-nav ul li:hover a {
+    color: #58a6ff;
+}
+
+.site-nav ul li.nav-current {
+    background: #1f2937;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #58a6ff;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+    color: #f0f6fc;
+}
+
+a {
+    color: #58a6ff;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #161b22;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #161b22;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+    color: #f0f6fc;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #8b949e;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #f85149;
+    font-style: italic;
+}
+
+/* -- Blog layout (single column, nav below content) --------------- */
+
+body[data-layout="blog"] {
+    display: block;
+}
+
+body[data-layout="blog"] article.blog-post {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 3rem;
+}
+
+body[data-layout="blog"] .site-nav {
+    border-right: none;
+    border-top: 1px solid #30363d;
+    padding: 1.5rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+body[data-layout="blog"] .site-nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #30363d;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
diff --git a/docs-src/asnotes-publish.themes.blog/default.css b/docs-src/asnotes-publish.themes.blog/default.css
new file mode 100644
index 0000000..a6ab4f1
--- /dev/null
+++ b/docs-src/asnotes-publish.themes.blog/default.css
@@ -0,0 +1,283 @@
+/* AS Notes default theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #24292e;
+    background: #ffffff;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #f6f8fa;
+    border-bottom: 1px solid #d0d7de;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #24292e;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #0366d6;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #d0d7de;
+    background: #f6f8fa;
+    font-size: 0.85rem;
+    color: #586069;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #0366d6;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #f6f8fa;
+    border-right: 1px solid #d0d7de;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #24292f;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #eaeef2;
+}
+
+.site-nav ul li:hover a {
+    color: #0550ae;
+}
+
+.site-nav ul li.nav-current {
+    background: #ddf4ff;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #0550ae;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+}
+
+a {
+    color: #0366d6;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #f6f8fa;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #f6f8fa;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #f6f8fa;
+    border: 1px solid #e1e4e8;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #586069;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #cb2431;
+    font-style: italic;
+}
+
+/* -- Blog layout (single column, nav below content) --------------- */
+
+body[data-layout="blog"] {
+    display: block;
+}
+
+body[data-layout="blog"] article.blog-post {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 3rem;
+}
+
+body[data-layout="blog"] .site-nav {
+    border-right: none;
+    border-top: 1px solid #d0d7de;
+    padding: 1.5rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+body[data-layout="blog"] .site-nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #d0d7de;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
diff --git a/docs-src/asnotes-publish.themes.notes/dark.css b/docs-src/asnotes-publish.themes.notes/dark.css
new file mode 100644
index 0000000..e550f68
--- /dev/null
+++ b/docs-src/asnotes-publish.themes.notes/dark.css
@@ -0,0 +1,285 @@
+/* AS Notes dark theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #c9d1d9;
+    background: #0d1117;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #161b22;
+    border-bottom: 1px solid #30363d;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #c9d1d9;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #58a6ff;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #30363d;
+    background: #161b22;
+    font-size: 0.85rem;
+    color: #8b949e;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #58a6ff;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #161b22;
+    border-right: 1px solid #30363d;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #c9d1d9;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #1f2937;
+}
+
+.site-nav ul li:hover a {
+    color: #58a6ff;
+}
+
+.site-nav ul li.nav-current {
+    background: #1f2937;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #58a6ff;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+    color: #f0f6fc;
+}
+
+a {
+    color: #58a6ff;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #161b22;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #161b22;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+    color: #f0f6fc;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #8b949e;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #f85149;
+    font-style: italic;
+}
+
+/* -- Blog layout (single column, nav below content) --------------- */
+
+body[data-layout="blog"] {
+    display: block;
+}
+
+body[data-layout="blog"] article.blog-post {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 3rem;
+}
+
+body[data-layout="blog"] .site-nav {
+    border-right: none;
+    border-top: 1px solid #30363d;
+    padding: 1.5rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+body[data-layout="blog"] .site-nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #30363d;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
diff --git a/docs-src/asnotes-publish.themes.notes/default.css b/docs-src/asnotes-publish.themes.notes/default.css
new file mode 100644
index 0000000..a6ab4f1
--- /dev/null
+++ b/docs-src/asnotes-publish.themes.notes/default.css
@@ -0,0 +1,283 @@
+/* AS Notes default theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #24292e;
+    background: #ffffff;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #f6f8fa;
+    border-bottom: 1px solid #d0d7de;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #24292e;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #0366d6;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #d0d7de;
+    background: #f6f8fa;
+    font-size: 0.85rem;
+    color: #586069;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #0366d6;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #f6f8fa;
+    border-right: 1px solid #d0d7de;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #24292f;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #eaeef2;
+}
+
+.site-nav ul li:hover a {
+    color: #0550ae;
+}
+
+.site-nav ul li.nav-current {
+    background: #ddf4ff;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #0550ae;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+}
+
+a {
+    color: #0366d6;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #f6f8fa;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #f6f8fa;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #f6f8fa;
+    border: 1px solid #e1e4e8;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #586069;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #cb2431;
+    font-style: italic;
+}
+
+/* -- Blog layout (single column, nav below content) --------------- */
+
+body[data-layout="blog"] {
+    display: block;
+}
+
+body[data-layout="blog"] article.blog-post {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 3rem;
+}
+
+body[data-layout="blog"] .site-nav {
+    border-right: none;
+    border-top: 1px solid #d0d7de;
+    padding: 1.5rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+body[data-layout="blog"] .site-nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #d0d7de;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
diff --git a/docs-src/assets/images/as-notes-editor-screenshot.png b/docs-src/assets/images/as-notes-editor-screenshot.png
new file mode 100644
index 0000000..090288a
Binary files /dev/null and b/docs-src/assets/images/as-notes-editor-screenshot.png differ
diff --git a/docs-src/blog/welcome-to-as-notes-blog.md b/docs-src/blog/welcome-to-as-notes-blog.md
new file mode 100644
index 0000000..90187e0
--- /dev/null
+++ b/docs-src/blog/welcome-to-as-notes-blog.md
@@ -0,0 +1,3 @@
+# Welcome to the AS Notes Blog
+
+This blog was generated using AS Notes publishing.
diff --git a/docs-src/pages/Backlinks.md b/docs-src/notes/Backlinks.md
similarity index 100%
rename from docs-src/pages/Backlinks.md
rename to docs-src/notes/Backlinks.md
diff --git a/docs-src/pages/Daily Journal.md b/docs-src/notes/Daily Journal.md
similarity index 100%
rename from docs-src/pages/Daily Journal.md
rename to docs-src/notes/Daily Journal.md
diff --git a/docs-src/pages/Encrypted Notes.md b/docs-src/notes/Encrypted Notes.md
similarity index 100%
rename from docs-src/pages/Encrypted Notes.md
rename to docs-src/notes/Encrypted Notes.md
diff --git a/docs-src/pages/Getting Started.md b/docs-src/notes/Getting Started.md
similarity index 100%
rename from docs-src/pages/Getting Started.md
rename to docs-src/notes/Getting Started.md
diff --git a/docs-src/pages/Images and Files.md b/docs-src/notes/Images and Files.md
similarity index 100%
rename from docs-src/pages/Images and Files.md
rename to docs-src/notes/Images and Files.md
diff --git a/docs-src/pages/Licence.md b/docs-src/notes/Licence.md
similarity index 100%
rename from docs-src/pages/Licence.md
rename to docs-src/notes/Licence.md
diff --git a/docs-src/notes/Publishing a Static Site.md b/docs-src/notes/Publishing a Static Site.md
new file mode 100644
index 0000000..ad2cf75
--- /dev/null
+++ b/docs-src/notes/Publishing a Static Site.md	
@@ -0,0 +1,934 @@
+# Publishing a Static Site
+
+AS Notes includes a built-in HTML conversion tool that turns your markdown notes into a static website. It supports filtering, layouts, themes, asset pipelines, retina images, SEO metadata, sitemaps, and RSS feeds. You can deploy to GitHub Pages, Netlify, Vercel, Cloudflare Pages, or any static hosting.
+
+This documentation is itself a working example -- it was written in AS Notes and published using the same tool.
+
+## How It Works
+
+The `publish` package recursively scans a folder of markdown files and converts them to HTML. Subdirectories are walked automatically, so notes organised in folders like `notes/`, `journals/`, and `pages/` are all discovered. The `templates` and `node_modules` directories are excluded by default.
+
+[[Wikilinks]] between pages are automatically resolved to the correct HTML links. A navigation sidebar is generated from all public pages. Only pages you mark as public are published.
+
+Output is flat: all HTML files are written to the output root regardless of source subdirectory depth. Filenames are slugified to clean, URL-friendly kebab-case: `notes/My Page.md` becomes `my-page.html`. This matches how wikilinks work in AS Notes where filenames are globally unique.
+
+Each page is wrapped in a layout template with class names you can style any way you like. Unstyled output is clean, readable HTML with zero dependencies.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) 20 or later
+- Your notes in a folder of `.md` files
+
+## Installation
+
+There are two ways to run the converter:
+
+### npm (recommended for CI/CD)
+
+Install the CLI globally or use npx:
+
+```bash
+npx asnotes-publish --config ./asnotes-publish.json
+```
+
+Or install globally:
+
+```bash
+npm install -g asnotes-publish
+asnotes-publish --config ./asnotes-publish.json
+```
+
+This is the recommended approach for CI/CD pipelines (GitHub Actions, Netlify, Vercel, Cloudflare Pages).
+
+### Build from source
+
+Alternatively, the `publish` package in the AS Notes repository can be built from source:
+
+```bash
+cd publish
+npm install
+npm run build
+node dist/convert.js --config ../asnotes-publish.json
+```
+
+### VS Code Extension
+
+The converter is also bundled into the AS Notes VS Code extension. Use the command palette (`Ctrl+Shift+P`) and run **AS Notes: Publish to HTML**. This prompts for an output directory and runs the conversion with your configured settings. No separate installation required.
+
+## Quick Start
+
+```bash
+npm run convert -- --input /path/to/notes --output /path/to/site --default-public
+```
+
+This converts all markdown files to HTML. The output folder is wiped and regenerated on every run.
+
+Preview locally:
+
+```bash
+npx serve /path/to/site
+```
+
+## Front Matter
+
+Control publishing behaviour per-page using YAML front matter at the top of any markdown file:
+
+```yaml
+---
+public: true
+title: My Page Title
+order: 1
+description: A short description for SEO
+layout: docs
+assets: true
+retina: true
+draft: false
+date: 2025-03-23
+---
+```
+
+All fields are optional. Here is what each field does:
+
+| Field | Type | Description |
+|---|---|---|
+| `public` | boolean | Page is included in output. Required unless `--default-public` is used |
+| `title` | string | Page title for `<title>` tag and nav. Defaults to filename |
+| `order` | number | Nav sort order. Lower numbers appear first. Unordered pages sort alphabetically after ordered ones |
+| `description` | string | Injected as `<meta name="description">` for SEO |
+| `layout` | string | Per-page layout override (`docs`, `blog`, `minimal`, or custom) |
+| `assets` | boolean | Enable asset copying for this page. Required unless `--default-assets` is used |
+| `retina` | boolean | Apply retina styling to all images on this page |
+| `draft` | boolean | Exclude from output unless `--include-drafts` is passed |
+| `date` | string | Date for blog-style display and RSS feed ordering |
+
+### Slash Commands for Front Matter
+
+In VS Code, type `/` in any markdown file to access these slash commands:
+
+- **/Public** -- toggle `public: true/false` in front matter
+- **/Layout** -- cycle through `docs`, `blog`, `minimal` layouts
+- **/Retina** -- toggle `retina: true/false`
+- **/Assets** -- toggle `assets: true/false`
+
+These commands create a front matter block if one doesn't exist, or update existing fields.
+
+## Public / Private Filtering
+
+By default, only pages with `public: true` in their front matter are converted. All other pages are skipped.
+
+```yaml
+---
+public: true
+---
+# This page will be published
+```
+
+Pages without front matter or without `public: true` are skipped silently.
+
+### Encrypted Files
+
+Files ending in `.enc.md` (AS Notes encrypted files) are always excluded from publishing. This is a hardcoded safety measure -- encrypted notes are never included in the output regardless of `--default-public` or per-file front matter settings.
+
+### Excluding Directories
+
+The converter recursively scans all subdirectories. The `templates` and `node_modules` directories are excluded by default. To exclude additional directories, use `--exclude`:
+
+```bash
+npm run convert -- --input ./notes --output ./site --default-public --exclude drafts --exclude archive
+```
+
+Exclude matches directory names at any depth in the tree.
+
+### Default Public Mode
+
+Pass `--default-public` to invert the behaviour: all pages are published unless they have `public: false`:
+
+```bash
+npm run convert -- --input ./notes --output ./site --default-public
+```
+
+### Dead Links
+
+When a public page links to a non-public page via [[wikilink]], the link is rendered as a dead link (the href is still present but points nowhere). The converter logs a warning for each dead link so you can fix them.
+
+### Drafts
+
+Pages with `draft: true` are excluded from the output. To include them (e.g. for a preview build), pass `--include-drafts`:
+
+```bash
+npm run convert -- --input ./notes --output ./site --default-public --include-drafts
+```
+
+### Home Page (Index)
+
+Every site needs a page at `/`. If your notes include a file called `index.md`, it becomes the home page automatically. The index page appears first in navigation and displays as "Home".
+
+If no `index.md` exists among your public pages, the converter auto-generates a simple index page that lists links to all published pages. The console will show:
+
+```
+[info] No index.md found - generating page index
+```
+
+To create a custom home page, add `index.md` to your notes root with `public: true`:
+
+```yaml
+---
+public: true
+title: Welcome
+---
+# Welcome to my site
+
+This is my home page.
+```
+
+## Asset Pipeline
+
+Images and files referenced in your markdown are automatically discovered and copied to the output directory.
+
+### Enabling Asset Copying
+
+Asset copying is opt-in for safety. You have two options:
+
+**Per-page:** Add `assets: true` to the page's front matter:
+
+```yaml
+---
+public: true
+assets: true
+---
+![screenshot](../assets/images/screenshot.png)
+```
+
+**Global:** Pass `--default-assets` to enable asset copying for all public pages:
+
+```bash
+npm run convert -- --input ./notes --output ./site --default-public --default-assets
+```
+
+With `--default-assets`, pages can opt out with `assets: false`.
+
+### How It Works
+
+The converter scans rendered HTML for local `<img src="...">` references. Each reference is resolved relative to the page's source location within the input directory. Since all HTML pages are output to a flat directory, the converter rewrites `src` attributes so that asset paths resolve correctly in the published output.
+
+For example, if `pages/My Page.md` references `../assets/images/photo.png`, the converter:
+
+1. Resolves the path relative to the page's source directory (`pages/`)
+2. Copies the file to the output directory as `assets/images/photo.png`
+3. Rewrites the `<img src>` in the HTML to `assets/images/photo.png`
+
+Absolute URLs (`http://`, `https://`) and data URIs are ignored.
+
+If a referenced file is missing, a warning is logged.
+
+### Manual Assets
+
+You can also copy specific files with `--asset`:
+
+```bash
+npm run convert -- --input ./notes --output ./site --asset /path/to/favicon.ico
+```
+
+## Stylesheets
+
+### CDN Stylesheets
+
+Pass `--stylesheet` with a URL:
+
+```bash
+npm run convert -- \
+  --input ./notes --output ./site \
+  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css
+```
+
+### Local Stylesheets
+
+Local file paths passed to `--stylesheet` are automatically copied to the output directory. No separate `--asset` flag is needed:
+
+```bash
+npm run convert -- \
+  --input ./notes --output ./site \
+  --stylesheet /path/to/my-styles.css
+```
+
+The file is copied to the output and referenced by filename in each page's `<head>`.
+
+### Combining Stylesheets
+
+Pass `--stylesheet` multiple times. Tags are injected in the order specified:
+
+```bash
+npm run convert -- \
+  --input ./notes --output ./site \
+  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css \
+  --stylesheet /path/to/layout.css
+```
+
+## Layouts
+
+Layouts control the HTML structure of each page. Three built-in layouts are available, and you can define your own.
+
+### Built-in Layouts
+
+Select a layout with `--layout`:
+
+| Layout | Description |
+|---|---|
+| `docs` | Navigation sidebar + content area with `markdown-body` class (default) |
+| `blog` | Navigation + blog-style article with date display |
+| `minimal` | Content only, no navigation |
+
+```bash
+npm run convert -- --input ./notes --output ./site --layout blog
+```
+
+### Per-page Layout Override
+
+Set `layout:` in front matter to override the global layout for a specific page:
+
+```yaml
+---
+public: true
+layout: minimal
+---
+```
+
+### Custom Layouts
+
+The setup wizard (Step 8) offers to create a **layouts directory** containing editable copies of all three built-in layouts. You can modify these files to customise the HTML structure of your site.
+
+Point the converter at your layouts directory with `--layouts`:
+
+```bash
+npm run convert -- --input ./notes --output ./site --layouts ./layouts --layout my-layout
+```
+
+The converter looks for `my-layout.html` in the layouts directory first, then falls back to the includes directory, then to built-in layouts.
+
+You can also create entirely new layout files in the layouts directory and reference them by name (without the `.html` extension) in `--layout` or per-page `layout:` front matter.
+
+Template tokens:
+
+| Token | Replaced with |
+|---|---|
+| `{{title}}` | Page title (escaped) |
+| `{{header}}` | Header partial HTML (from `header.html` in includes dir) |
+| `{{nav}}` | Navigation HTML |
+| `{{content}}` | Rendered markdown body |
+| `{{stylesheets}}` | `<link>` tags for stylesheets |
+| `{{meta}}` | `<meta name="description">` tag |
+| `{{date}}` | `<time>` element (if page has `date:` front matter) |
+| `{{toc}}` | Table of contents HTML |
+| `{{footer}}` | Footer partial HTML (from `footer.html` in includes dir) |
+| `{{base-url}}` | Base URL path prefix |
+
+Example custom layout:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body>
+{{header}}
+    <header>{{nav}}</header>
+    <main>
+        {{toc}}
+        {{date}}
+        {{content}}
+    </main>
+{{footer}}
+</body>
+</html>
+```
+
+### Header and Footer Partials
+
+Add a consistent header and footer across all pages by creating `header.html` and `footer.html` in your includes directory.
+
+The converter looks for these files when `--includes` is set (or `includes` is set in the config file). If a partial exists, its contents are wrapped in a `<header>` or `<footer>` element and injected into the page. If a partial does not exist, an HTML comment (`<!-- header -->` or `<!-- footer -->`) is emitted as a placeholder.
+
+Partials support `{{base-url}}` and `{{title}}` tokens so you can create dynamic links.
+
+Example `header.html`:
+
+```html
+<div class="site-header">
+    <a class="site-title" href="{{base-url}}/">My Notes</a>
+    <span class="header-sep">|</span>
+    <a href="https://github.com/me">GitHub</a>
+    <a href="mailto:me@example.com">Contact</a>
+</div>
+```
+
+Example `footer.html`:
+
+```html
+<div class="site-footer">
+    <p>&copy; 2026 My Name. Built with <a href="https://www.asnotes.io">AS Notes</a>.</p>
+</div>
+```
+
+Both built-in and custom layouts include `{{header}}` and `{{footer}}` tokens, so partials work with any layout.
+
+When using the VS Code publish wizard, the includes directory step (step 8) offers three options: create default `header.html` and `footer.html` files, browse for an existing includes directory, or skip. Edit the generated files to add your own navigation, branding, and contact information.
+
+### Custom Navigation
+
+By default, the converter auto-generates a sidebar navigation listing all published pages in order. To take full control of navigation content and structure, create a `nav.md` file at the root of your input directory.
+
+`nav.md` is rendered as markdown with full wikilink support, so you can use headings, horizontal rules, lists, and links to organise your navigation however you like:
+
+```markdown
+## Guides
+
+- [[Getting Started]]
+- [[Publishing a Static Site]]
+
+---
+
+## Reference
+
+- [[Settings]]
+- [[Wikilinks]]
+```
+
+The rendered HTML replaces the auto-generated `<nav class="site-nav">` element on every page.
+
+**How it works:**
+
+- If `nav.md` exists in the input directory root, it is used as the navigation for all pages
+- If `nav.md` does not exist, the auto-generated navigation is used (with `nav-current` highlighting)
+- `nav.md` is not published as a standalone page and does not appear in the sitemap
+- Wikilinks in `nav.md` are resolved to their HTML page slugs, with `--base-url` applied if set
+- The `nav-current` CSS class is not applied when using custom navigation (since the content is user-controlled)
+
+**Multi-site support:** Since `nav.md` lives in the input directory, each site configuration can have its own navigation when using multi-site publishing.
+
+## Themes
+
+Built-in CSS themes provide ready-made styling without writing CSS:
+
+```bash
+npm run convert -- --input ./notes --output ./site --theme default
+```
+
+Available themes:
+
+| Theme | Description |
+|---|---|
+| `default` | Light theme with GitHub-inspired typography |
+| `dark` | Dark theme with dark background |
+
+Themes are injected as the first stylesheet, so you can override them with additional `--stylesheet` flags.
+
+## Retina Images
+
+Display high-resolution images at half their natural dimensions for crisp rendering on retina displays.
+
+### Three Levels of Control
+
+**Per-image:** Append `{.retina}` to the image alt text in markdown:
+
+```markdown
+![screenshot {.retina}](assets/images/screenshot@2x.png)
+```
+
+**Per-page:** Add `retina: true` to the page's front matter. All images on that page get the retina class:
+
+```yaml
+---
+public: true
+retina: true
+---
+```
+
+**Global:** Pass `--retina` to apply retina styling to all images across the site:
+
+```bash
+npm run convert -- --input ./notes --output ./site --retina
+```
+
+All three levels add a `retina` CSS class to the `<img>` tag. Style it in your CSS to control rendering size via `width` and `height` attributes.
+
+## SEO Features
+
+### Page Descriptions
+
+Add `description:` to front matter for SEO metadata:
+
+```yaml
+---
+public: true
+description: Learn how to publish AS Notes as a static website
+---
+```
+
+This injects `<meta name="description" content="...">` in the page `<head>`.
+
+### Slug URLs
+
+Output filenames are automatically slugified to clean, URL-friendly kebab-case. This produces shorter, more readable URLs that are better for SEO and sharing:
+
+| Source file | Output file |
+|---|---|
+| `Getting Started.md` | `getting-started.html` |
+| `My Cool Page.md` | `my-cool-page.html` |
+| `Page & Notes.md` | `page-notes.html` |
+| `index.md` | `index.html` |
+
+All wikilinks, navigation, sitemap, and RSS feed hrefs use the slugified filenames automatically.
+
+### Base URL
+
+When deploying to a subdirectory (e.g. `https://example.com/docs/`), set the base URL prefix:
+
+```bash
+npm run convert -- --input ./notes --output ./site --base-url /docs
+```
+
+This prefixes all navigation links and asset references with `/docs/`.
+
+### Sitemap
+
+A `sitemap.xml` is automatically generated in the output directory containing all public pages. If pages have a `date:` field, it is included as `<lastmod>`.
+
+### RSS / Atom Feed
+
+An RSS feed (`feed.xml`) is generated for pages with a `date:` field, sorted newest-first. This enables blog-style subscriptions.
+
+## Table of Contents
+
+Every page automatically gets a table of contents generated from its `h2`, `h3`, and `h4` headings. The TOC is rendered as a collapsible `<details>` element at the top of the content area.
+
+Headings automatically receive `id` attributes for deep linking.
+
+## HTML Structure Reference
+
+Here is the HTML structure the `docs` layout produces:
+
+```html
+<body>
+  <header>
+    <!-- contents of header.html, or an HTML comment if not set -->
+  </header>
+  <nav class="site-nav">
+    <ul>
+      <li><a href="index.html">Home</a></li>
+      <li class="nav-current"><a href="my-page.html">My Page</a></li>
+    </ul>
+  </nav>
+  <article class="markdown-body">
+    <nav class="toc">
+      <details open>
+        <summary>Contents</summary>
+        <ul>
+          <li><a href="#section">Section</a></li>
+        </ul>
+      </details>
+    </nav>
+    <!-- rendered markdown -->
+  </article>
+  <footer>
+    <!-- contents of footer.html, or an HTML comment if not set -->
+  </footer>
+</body>
+```
+
+Key classes:
+
+| Class | Element | Notes |
+|---|---|---|
+| `site-header` | `<div>` | Default header partial wrapper (customise in `header.html`) |
+| `site-footer` | `<div>` | Default footer partial wrapper (customise in `footer.html`) |
+| `site-nav` | `<nav>` | Sidebar navigation (auto-generated or from `nav.md`) |
+| `nav-current` | `<li>` | Currently active page |
+| `markdown-body` | `<article>` | Content area (docs layout) -- compatible with github-markdown-css |
+| `blog-post` | `<article>` | Content area (blog layout) |
+| `toc` | `<nav>` | Table of contents |
+| `page-date` | `<time>` | Date display (blog layout) |
+| `retina` | `<img>` | Retina-sized image |
+| `missing-page` | `<p>` | Placeholder page for unresolved wikilinks |
+
+## CLI Reference
+
+```
+asnotes-publish --input <dir> --output <dir> [options]
+asnotes-publish --config <file> [options]
+
+Options:
+  --config <file>           Load settings from a JSON config file
+  --stylesheet <url|file>   Add a stylesheet (repeatable)
+  --asset <file>            Copy a file to output (repeatable)
+  --default-public          Treat all pages as public unless public: false
+  --default-assets          Copy referenced assets unless assets: false
+  --layout <name>           Layout template: docs, blog, minimal (default: docs)
+  --layouts <path>          Directory containing editable layout templates
+  --includes <path>         Directory for custom headers and footers
+  --theme <name>            Built-in CSS theme: default, dark
+  --retina                  Enable retina image sizing globally
+  --base-url <prefix>       URL path prefix for links and assets
+  --include-drafts          Include pages with draft: true
+  --exclude <dirname>       Exclude a directory from scanning (repeatable)
+
+When --config is used, --input defaults to the config file's directory.
+CLI flags override config file values.
+
+Default excluded directories: templates, node_modules
+```
+
+## Config File
+
+Publish settings are stored in a JSON config file at the root of your notes directory (next to `.asnotes/`). Both the VS Code extension and the CLI read from this file.
+
+The default filename is `asnotes-publish.json`. When publishing from a subdirectory, the filename includes the directory name: `asnotes-publish.<dirname>.json` (e.g. `asnotes-publish.docs-src.json`). See [Multi-Site Publishing](#multi-site-publishing) below.
+
+### Schema
+
+```json
+{
+    "inputDir": "",
+    "defaultPublic": true,
+    "defaultAssets": true,
+    "layout": "docs",
+    "layouts": "./layouts",
+    "includes": "./includes",
+    "theme": "default",
+    "baseUrl": "/my-repo",
+    "retina": false,
+    "includeDrafts": false,
+    "stylesheets": [
+        "https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css"
+    ],
+    "exclude": ["drafts", "archive"],
+    "outputDir": "./site"
+}
+```
+
+The wizard writes all fields with their defaults so you can discover every available option by reading the file.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `inputDir` | string | `""` | Input directory relative to config file. Empty string means notes root |
+| `defaultPublic` | boolean | `false` | Publish all pages unless `public: false` |
+| `defaultAssets` | boolean | `false` | Copy referenced assets unless `assets: false` |
+| `layout` | string | `"docs"` | Layout template: `docs`, `blog`, `minimal` |
+| `layouts` | string | `""` | Directory containing editable layout templates |
+| `includes` | string | `""` | Directory for custom headers and footers |
+| `theme` | string | `""` | Built-in CSS theme: `default`, `dark` |
+| `baseUrl` | string | `""` | URL path prefix for links and assets |
+| `retina` | boolean | `false` | Enable retina image sizing globally |
+| `includeDrafts` | boolean | `false` | Include pages with `draft: true` |
+| `stylesheets` | string[] | `[]` | Stylesheet URLs or local file paths |
+| `exclude` | string[] | `[]` | Additional directory names to exclude |
+| `outputDir` | string | `""` | Output directory (relative to config file or absolute) |
+
+### Using --config
+
+Pass `--config` to the CLI to load settings from the file:
+
+```bash
+asnotes-publish --config ./asnotes-publish.json
+```
+
+When `--config` is used:
+
+- `--input` defaults to `inputDir` from the config (resolved relative to the config file), then falls back to the config file's parent directory
+- `--output` defaults to the `outputDir` value in the config (resolved relative to the config file)
+- CLI flags override any config file values
+
+This means a minimal CI/CD invocation with a config file is:
+
+```bash
+npx asnotes-publish --config ./asnotes-publish.json
+```
+
+You can override individual settings:
+
+```bash
+npx asnotes-publish --config ./asnotes-publish.json --include-drafts --output ./preview
+```
+
+### Multi-Site Publishing
+
+You can publish multiple sites from the same workspace by creating separate config files. Each config file targets a different input directory.
+
+The config filename is derived from the input directory name:
+
+| Input directory | Config filename |
+|---|---|
+| Notes root | `asnotes-publish.json` |
+| `./docs-src` | `asnotes-publish.docs-src.json` |
+| `./blog` | `asnotes-publish.blog.json` |
+| `./pages` | `asnotes-publish.pages.json` |
+
+For example, a workspace with both documentation and a blog might have:
+
+```
+my-notes/
+  .asnotes/
+  asnotes-publish.docs-src.json    # publishes docs-src/ to site/
+  asnotes-publish.blog.json        # publishes blog/ to blog-site/
+  docs-src/
+    pages/
+      Getting Started.md
+      ...
+  blog/
+    2025-01-01 First Post.md
+    ...
+```
+
+Build each site separately:
+
+```bash
+npx asnotes-publish --config ./asnotes-publish.docs-src.json
+npx asnotes-publish --config ./asnotes-publish.blog.json
+```
+
+The VS Code extension discovers all config files automatically and shows a picker when multiple exist.
+
+### Settings to CLI Flag Mapping
+
+If you prefer CLI flags over a config file, here is the mapping:
+
+| Config field | CLI flag |
+|---|---|
+| `inputDir` | `--input <dir>` |
+| `defaultPublic` | `--default-public` |
+| `defaultAssets` | `--default-assets` |
+| `layout` | `--layout <name>` |
+| `layouts` | `--layouts <path>` |
+| `includes` | `--includes <path>` |
+| `theme` | `--theme <name>` |
+| `baseUrl` | `--base-url <prefix>` |
+| `retina` | `--retina` |
+| `includeDrafts` | `--include-drafts` |
+| `stylesheets` | `--stylesheet <url>` (repeatable) |
+| `exclude` | `--exclude <dirname>` (repeatable) |
+| `outputDir` | `--output <dir>` |
+
+## VS Code Integration
+
+### Publish Command
+
+Use the command palette (`Ctrl+Shift+P`) and run **AS Notes: Publish to HTML**.
+
+If no publish config exists, a setup wizard walks you through:
+
+1. **Input directory** -- notes root or a subdirectory
+2. **Default public** -- publish all pages by default?
+3. **Default assets** -- copy referenced images and files?
+4. **Layout** -- docs, blog, or minimal
+5. **Theme** -- default, dark, or none
+6. **Base URL** -- path prefix for deployed site
+7. **Output directory** -- where to write the HTML
+8. **Layouts directory** -- create default editable layouts, browse for an existing directory, or skip
+9. **Includes directory** -- create default includes, browse for an existing directory, or skip
+
+The wizard saves your choices to the appropriate config file (e.g. `asnotes-publish.json` or `asnotes-publish.docs-src.json`). All fields are written with defaults so you can discover every option by reading the JSON file.
+
+On subsequent runs with a single config, the converter uses the saved settings immediately -- no wizard, no prompts. With multiple config files, a picker lets you choose which site to publish or create a new configuration.
+
+### Configure Publish Settings
+
+To change your publish settings without building, run **AS Notes: Configure Publish Settings** from the command palette. This shows a picker of existing configs to edit or creates a new one. If you change the input directory, the config file is renamed automatically to match.
+
+You can also edit config files directly -- they are standard JSON.
+
+```
+
+## Publishing to GitHub Pages
+
+### 1. Enable GitHub Pages
+
+In your repository, go to **Settings > Pages** and set the source to **GitHub Actions**.
+
+### 2. Add a CI Workflow
+
+Create `.github/workflows/pages.yml`:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npx asnotes-publish --config ./asnotes-publish.json --base-url /${{ github.event.repository.name }}
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+Adjust `--config` path and any flag overrides to match your repository layout. The `--base-url` override is needed for GitHub Pages subdirectory deployment. All other settings come from `asnotes-publish.json`.
+
+Alternatively, you can use explicit flags instead of a config file:
+
+```yaml
+      - run: >
+          npx asnotes-publish
+          --input ./notes
+          --output ./site
+          --default-public
+          --default-assets
+          --theme default
+          --base-url /${{ github.event.repository.name }}
+```
+
+### Custom Domain
+
+To serve from a custom domain (e.g. `docs.example.com`):
+
+1. Add a DNS `CNAME` record pointing to `<your-github-username>.github.io`
+2. Add a step after the convert step to write the `CNAME` file (the converter wipes output on each run):
+
+   ```yaml
+   - run: echo "docs.example.com" > ./site/CNAME
+   ```
+
+3. Enter the domain in **Settings > Pages > Custom domain** and enable **Enforce HTTPS**
+4. Remove `--base-url` since you're serving from the domain root
+
+## Publishing to Netlify
+
+### 1. Create a `netlify.toml`
+
+Add this to your repository root:
+
+```toml
+[build]
+  command = "npx asnotes-publish --config ./asnotes-publish.json"
+  publish = "site"
+
+[build.environment]
+  NODE_VERSION = "20"
+```
+
+### 2. Connect Your Repository
+
+1. Log in to [Netlify](https://www.netlify.com) and click **Add new site > Import an existing project**
+2. Connect your Git provider and select your repository
+3. Netlify auto-detects the `netlify.toml` settings
+4. Click **Deploy site**
+
+Netlify automatically builds and deploys on every push. No `--base-url` is needed since Netlify serves from the domain root.
+
+### Custom Domain
+
+In **Site settings > Domain management**, add your custom domain and follow Netlify's DNS instructions.
+
+## Publishing to Vercel
+
+### 1. Configure Vercel
+
+Create `vercel.json` in your repository root:
+
+```json
+{
+    "buildCommand": "npx asnotes-publish --config ./asnotes-publish.json",
+    "outputDirectory": "site",
+    "framework": null
+}
+```
+
+### 2. Connect Your Repository
+
+1. Log in to [Vercel](https://vercel.com) and click **Add New > Project**
+2. Import your Git repository
+3. Vercel reads `vercel.json` for build settings
+4. Click **Deploy**
+
+Vercel deploys on every push and provides a preview URL for each branch.
+
+## Publishing to Cloudflare Pages
+
+### 1. Connect Your Repository
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and go to **Compute** > **Workers & Pages**
+2. Click **Create application > Pages > Connect to Git**
+3. Select your repository
+
+### 2. Configure Build Settings
+
+| Setting | Value |
+|---|---|
+| Build command | `npx asnotes-publish --config ./asnotes-publish.json` |
+| Build output directory | `site` |
+| Node.js version | `20` (set as environment variable `NODE_VERSION`) |
+
+Click **Save and Deploy**. Cloudflare Pages deploys on every push with automatic preview deployments for branches.
+
+## Writing a Custom Layout CSS
+
+This documentation site uses a two-column grid layout. Save this as `layout.css`:
+
+```css
+*, *::before, *::after { box-sizing: border-box; }
+
+body {
+  display: grid;
+  grid-template-columns: 220px 1fr;
+  min-height: 100vh;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+}
+
+nav.site-nav {
+  background: #f6f8fa;
+  border-right: 1px solid #d0d7de;
+  padding: 1.5rem 1rem;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow-y: auto;
+}
+
+nav.site-nav ul { list-style: none; margin: 0; padding: 0; }
+
+nav.site-nav a {
+  display: block;
+  padding: 0.3rem 0.6rem;
+  border-radius: 6px;
+  text-decoration: none;
+  color: #24292f;
+  font-size: 0.875rem;
+}
+
+nav.site-nav a:hover { background: #eaeef2; color: #0550ae; }
+nav.site-nav .nav-current a { background: #ddf4ff; color: #0550ae; font-weight: 600; }
+
+article.markdown-body { padding: 2rem 3rem; max-width: 900px; }
+
+@media (max-width: 700px) {
+  body { grid-template-columns: 1fr; }
+  nav.site-nav { position: relative; height: auto; border-right: none; border-bottom: 1px solid #d0d7de; }
+  article.markdown-body { padding: 1.5rem; }
+}
+```
+
+Then convert:
+
+```bash
+npm run convert -- \
+  --input ./notes --output ./site \
+  --default-public --default-assets \
+  --stylesheet /path/to/layout.css
+```
diff --git a/docs-src/pages/Settings.md b/docs-src/notes/Settings.md
similarity index 100%
rename from docs-src/pages/Settings.md
rename to docs-src/notes/Settings.md
diff --git a/docs-src/pages/Slash Commands.md b/docs-src/notes/Slash Commands.md
similarity index 100%
rename from docs-src/pages/Slash Commands.md
rename to docs-src/notes/Slash Commands.md
diff --git a/docs-src/pages/Task Management.md b/docs-src/notes/Task Management.md
similarity index 100%
rename from docs-src/pages/Task Management.md
rename to docs-src/notes/Task Management.md
diff --git a/docs-src/pages/Troubleshooting.md b/docs-src/notes/Troubleshooting.md
similarity index 100%
rename from docs-src/pages/Troubleshooting.md
rename to docs-src/notes/Troubleshooting.md
diff --git a/docs-src/pages/Wikilinks.md b/docs-src/notes/Wikilinks.md
similarity index 100%
rename from docs-src/pages/Wikilinks.md
rename to docs-src/notes/Wikilinks.md
diff --git a/docs-src/pages/index.md b/docs-src/notes/index.md
similarity index 96%
rename from docs-src/pages/index.md
rename to docs-src/notes/index.md
index c2bca56..b14ce2c 100644
--- a/docs-src/pages/index.md
+++ b/docs-src/notes/index.md
@@ -8,6 +8,8 @@ AS Notes is a VS Code extension that turns your editor into a Personal Knowledge
 
 > **GitHub:** [https://github.com/appsoftwareltd/as-notes](https://github.com/appsoftwareltd/as-notes)
 
+![AS Notes editor screenshot](../assets/images/as-notes-editor-screenshot.png)
+
 ## Why VS Code?
 
 Using VS Code as your notes app gives you a huge amount for free before you even start using AS Notes features:
@@ -58,4 +60,4 @@ AS Notes is privacy-first. It never connects to external servers. All indexing,
 
 ## Licence
 
-See [[Licence Rationale]] for an explanation of the source-available licence model.
\ No newline at end of file
+See [[Licence Rationale]] for an explanation of the source-available licence model.
diff --git a/docs-src/pages/Publishing a Static Site.md b/docs-src/pages/Publishing a Static Site.md
deleted file mode 100644
index 5085a8b..0000000
--- a/docs-src/pages/Publishing a Static Site.md	
+++ /dev/null
@@ -1,253 +0,0 @@
-# Publishing a Static Site
-
-AS Notes includes a built-in HTML conversion tool that turns your markdown notes into a static website. You can use this to publish your knowledge base as a standalone site or deploy it to GitHub Pages.
-
-This documentation is itself a working example — it was written in AS Notes and published using the same tool.
-
-## How It Works
-
-The `html-conversion` package scans a folder of markdown files and converts them to HTML. [[Wikilinks]] between pages are automatically resolved to the correct HTML links. A navigation sidebar is generated automatically from the list of pages.
-
-Each page is wrapped in semantic HTML with class names you can style any way you like — or not at all. Unstyled output is clean, readable HTML with zero dependencies.
-
-## Prerequisites
-
-- [Node.js](https://nodejs.org) 20 or later
-- Your notes in a folder of `.md` files
-
-## Standalone Usage
-
-### 1. Install the converter
-
-Clone or download the `html-conversion` package from the AS Notes repository, then install dependencies:
-
-```bash
-cd html-conversion
-npm install
-npm run build
-```
-
-### 2. Convert your notes
-
-```bash
-npm run convert -- --input /path/to/your/notes --output /path/to/output
-```
-
-The output folder is wiped and regenerated on every run. Open any `.html` file in a browser to preview, or serve the folder with a local file server:
-
-```bash
-npx serve /path/to/output
-```
-
-## Adding Styles
-
-By default the output is unstyled HTML. You can inject any stylesheet — a CDN link, a local file, or both — without touching the converter itself.
-
-### Using a CDN stylesheet
-
-Pass `--stylesheet` with a URL. You can repeat the flag to add multiple stylesheets in order:
-
-```bash
-npm run convert -- \
-  --input /path/to/notes \
-  --output /path/to/output \
-  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css
-```
-
-Every generated page will include that `<link>` tag in its `<head>`. The content area uses `<article class="markdown-body">`, which is the class expected by [github-markdown-css](https://github.com/sindresorhus/github-markdown-css) — so the above just works.
-
-### Using a local stylesheet
-
-Use `--asset` to copy a local CSS file into the output folder, then reference it by filename with `--stylesheet`:
-
-```bash
-npm run convert -- \
-  --input /path/to/notes \
-  --output /path/to/output \
-  --stylesheet my-styles.css \
-  --asset /path/to/my-styles.css
-```
-
-`--asset` copies the file into the output directory. `--stylesheet` injects it as a relative `<link href="my-styles.css">`.
-
-Because the output folder is wiped on each run, any CSS you want in the output **must** be passed via `--asset` — files placed there manually will be deleted.
-
-### Combining CDN and local stylesheets
-
-You can pass `--stylesheet` and `--asset` as many times as you need, in any order:
-
-```bash
-npm run convert -- \
-  --input /path/to/notes \
-  --output /path/to/output \
-  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css \
-  --stylesheet layout.css \
-  --asset /path/to/layout.css
-```
-
-Stylesheet `<link>` tags are injected in the order you specify them.
-
-## Writing a Custom Layout (like this site)
-
-This documentation site uses a two-column grid layout with a styled sidebar nav. Here is the CSS pattern used — save it as `layout.css` alongside your notes:
-
-```css
-*, *::before, *::after { box-sizing: border-box; }
-
-body {
-  display: grid;
-  grid-template-columns: 220px 1fr;
-  min-height: 100vh;
-  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-}
-
-/* Sidebar */
-nav.site-nav {
-  background: #f6f8fa;
-  border-right: 1px solid #d0d7de;
-  padding: 1.5rem 1rem;
-  position: sticky;
-  top: 0;
-  height: 100vh;
-  overflow-y: auto;
-}
-
-nav.site-nav ul { list-style: none; margin: 0; padding: 0; }
-
-nav.site-nav a {
-  display: block;
-  padding: 0.3rem 0.6rem;
-  border-radius: 6px;
-  text-decoration: none;
-  color: #24292f;
-  font-size: 0.875rem;
-}
-
-nav.site-nav a:hover      { background: #eaeef2; color: #0550ae; }
-nav.site-nav .nav-current a { background: #ddf4ff; color: #0550ae; font-weight: 600; }
-
-/* Content */
-article.markdown-body { padding: 2rem 3rem; max-width: 900px; }
-
-/* Responsive */
-@media (max-width: 700px) {
-  body { grid-template-columns: 1fr; }
-  nav.site-nav { position: relative; height: auto; border-right: none; border-bottom: 1px solid #d0d7de; }
-  article.markdown-body { padding: 1.5rem; }
-}
-
-/* Dark mode */
-@media (prefers-color-scheme: dark) {
-  body { background: #0d1117; color: #e6edf3; }
-  nav.site-nav { background: #161b22; border-right-color: #30363d; }
-  nav.site-nav a { color: #c9d1d9; }
-  nav.site-nav a:hover { background: #21262d; color: #58a6ff; }
-  nav.site-nav .nav-current a { background: #1c2d3e; color: #58a6ff; }
-}
-```
-
-Then convert using both the markdown CSS and your layout file:
-
-```bash
-npm run convert -- \
-  --input /path/to/notes \
-  --output /path/to/output \
-  --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css \
-  --stylesheet layout.css \
-  --asset /path/to/layout.css
-```
-
-### HTML structure reference
-
-If you're writing your own stylesheet, here's what the converter outputs:
-
-```html
-<body>
-  <nav class="site-nav">
-    <ul>
-      <li><a href="index.html">Home</a></li>
-      <li class="nav-current"><a href="my-page.html">My Page</a></li>
-      ...
-    </ul>
-  </nav>
-  <article class="markdown-body">
-    <!-- your converted markdown here -->
-  </article>
-</body>
-```
-
-Key classes:
-
-| Class | Element | Notes |
-|---|---|---|
-| `site-nav` | `<nav>` | The sidebar navigation |
-| `nav-current` | `<li>` | The currently active page |
-| `markdown-body` | `<article>` | The content area — compatible with github-markdown-css |
-| `missing-page` | `<p>` | Shown on auto-generated placeholder pages for unresolved wikilinks |
-
-## Publishing to GitHub Pages
-
-### 1. Enable GitHub Pages
-
-In your repository go to **Settings → Pages** and set the source to **GitHub Actions**.
-
-### 2. Add a CI workflow
-
-Create `.github/workflows/pages.yml` in your repository:
-
-```yaml
-name: Deploy to GitHub Pages
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm ci
-        working-directory: html-conversion
-      - run: npm run build
-        working-directory: html-conversion
-      - run: >
-          npm run convert --
-          --input ../notes
-          --output ../site
-          --stylesheet https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown-light.css
-          --stylesheet layout.css
-          --asset ../notes/layout.css
-        working-directory: html-conversion
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-      - id: deployment
-        uses: actions/deploy-pages@v4
-```
-
-Adjust `--input`, `--output`, and `--asset` paths to match your repository layout. Remove the `--stylesheet` and `--asset` flags if you don't need custom styles.
-
-### Custom Domain
-
-If you want to serve from a custom domain (e.g. `docs.example.com`):
-
-1. Add a DNS `CNAME` record pointing to `<your-github-username>.github.io`.
-2. Add a step **after** the convert step to write the `CNAME` file (the converter wipes the output on each run, so this must happen after):
-   ```yaml
-   - run: echo "docs.example.com" > ../site/CNAME
-     working-directory: html-conversion
-   ```
-3. Enter the domain in **Settings → Pages → Custom domain** and wait for DNS verification.
-4. Once verified, enable **Enforce HTTPS**.
-
-> **Note:** If your repository belongs to a GitHub organisation that has a custom domain configured at the org level, GitHub will apply that domain automatically to all repos. In that case you either configure a per-repo custom domain as above, or complete the org-level DNS setup to make the org domain work.
diff --git a/docs-src/templates/Journal.md b/docs-src/templates/Journal.md
new file mode 100644
index 0000000..1897d95
--- /dev/null
+++ b/docs-src/templates/Journal.md
@@ -0,0 +1 @@
+# {{date}}
diff --git a/html-conversion/README.md b/html-conversion/README.md
deleted file mode 100644
index 75379f7..0000000
--- a/html-conversion/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# AS Notes HTML Conversion
-
-`node dist/convert.js --input ../docs-src/pages --output ../docs`
\ No newline at end of file
diff --git a/html-conversion/package.json b/html-conversion/package.json
deleted file mode 100644
index 8e4f970..0000000
--- a/html-conversion/package.json
+++ /dev/null
@@ -1,27 +0,0 @@
-{
-    "name": "as-notes-html-conversion",
-    "version": "1.0.0",
-    "private": true,
-    "type": "module",
-    "main": "./dist/convert.js",
-    "bin": {
-        "as-notes-convert": "./dist/convert.js"
-    },
-    "scripts": {
-        "build": "node build.mjs",
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "lint": "tsc --noEmit",
-        "convert": "node dist/convert.js"
-    },
-    "dependencies": {
-        "as-notes-common": "file:../common",
-        "markdown-it": "^14.1.1"
-    },
-    "devDependencies": {
-        "@types/node": "^20.11.0",
-        "esbuild": "^0.24.0",
-        "typescript": "^5.7.0",
-        "vitest": "^3.0.0"
-    }
-}
\ No newline at end of file
diff --git a/html-conversion/src/convert.ts b/html-conversion/src/convert.ts
deleted file mode 100644
index f85944e..0000000
--- a/html-conversion/src/convert.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import MarkdownIt from 'markdown-it';
-import { WikilinkService, wikilinkPlugin } from 'as-notes-common';
-import { FileResolver } from './FileResolver.js';
-import { taskTagPlugin } from './TaskTagPlugin.js';
-
-function parseArgs(argv: string[]): { input: string; output: string; stylesheets: string[]; assets: string[] } {
-    let input = '';
-    let output = '';
-    const stylesheets: string[] = [];
-    const assets: string[] = [];
-
-    for (let i = 2; i < argv.length; i++) {
-        if (argv[i] === '--input' && i + 1 < argv.length) {
-            input = argv[++i];
-        } else if (argv[i] === '--output' && i + 1 < argv.length) {
-            output = argv[++i];
-        } else if (argv[i] === '--stylesheet' && i + 1 < argv.length) {
-            stylesheets.push(argv[++i]);
-        } else if (argv[i] === '--asset' && i + 1 < argv.length) {
-            assets.push(argv[++i]);
-        }
-    }
-
-    if (!input || !output) {
-        console.error('Usage: as-notes-convert --input <dir> --output <dir> [--stylesheet <url>]... [--asset <file>]...');
-        process.exit(1);
-    }
-
-    return { input: path.resolve(input), output: path.resolve(output), stylesheets, assets };
-}
-
-function scanMarkdownFiles(dir: string): string[] {
-    return fs.readdirSync(dir)
-        .filter(f => f.endsWith('.md'))
-        .sort();
-}
-
-function buildNav(resolver: FileResolver, currentPage: string): string {
-    const pages = resolver.listPages();
-    const items = pages.map(p => {
-        const isCurrent = p.name === currentPage ? ' class="nav-current"' : '';
-        const displayName = p.name === 'index' ? 'Home' : p.name;
-        return `        <li${isCurrent}><a href="${p.href}">${displayName}</a></li>`;
-    });
-
-    return `    <nav class="site-nav">\n      <ul>\n${items.join('\n')}\n      </ul>\n    </nav>`;
-}
-
-function wrapHtml(title: string, nav: string, body: string, stylesheets: string[] = []): string {
-    const linkTags = stylesheets.length > 0
-        ? '\n' + stylesheets.map(s => `    <link rel="stylesheet" href="${escapeHtml(s)}">`).join('\n')
-        : '';
-
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${escapeHtml(title)}</title>${linkTags}
-</head>
-<body>
-${nav}
-    <article class="markdown-body">
-${body}
-    </article>
-</body>
-</html>
-`;
-}
-
-function escapeHtml(text: string): string {
-    return text
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
-}
-
-function main(): void {
-    const { input, output, stylesheets, assets } = parseArgs(process.argv);
-
-    // Wipe output directory
-    if (fs.existsSync(output)) {
-        fs.rmSync(output, { recursive: true });
-    }
-    fs.mkdirSync(output, { recursive: true });
-
-    // Copy assets into output directory
-    for (const assetPath of assets) {
-        const resolvedAsset = path.resolve(assetPath);
-        const assetFilename = path.basename(resolvedAsset);
-        fs.copyFileSync(resolvedAsset, path.join(output, assetFilename));
-        console.log(`  [asset] ${assetFilename}`);
-    }
-
-    // Scan input for markdown files
-    const mdFiles = scanMarkdownFiles(input);
-    if (mdFiles.length === 0) {
-        console.error(`No .md files found in ${input}`);
-        process.exit(1);
-    }
-
-    // Build resolver from filenames
-    const resolver = new FileResolver(mdFiles);
-
-    // Set up markdown-it with wikilink plugin
-    const wikilinkService = new WikilinkService();
-    const md = new MarkdownIt({ html: true });
-    wikilinkPlugin(md, {
-        wikilinkService,
-        resolver: resolver.createResolverFn(),
-    });
-    md.use(taskTagPlugin);
-
-    // Convert each file
-    for (const filename of mdFiles) {
-        const pageName = filename.replace(/\.md$/i, '');
-        const inputPath = path.join(input, filename);
-        const outputPath = path.join(output, pageName + '.html');
-
-        const markdown = fs.readFileSync(inputPath, 'utf-8');
-        const htmlBody = md.render(markdown);
-
-        const title = pageName === 'index' ? 'AS Notes Documentation' : pageName;
-        const nav = buildNav(resolver, pageName);
-        const html = wrapHtml(title, nav, htmlBody, stylesheets);
-
-        fs.writeFileSync(outputPath, html, 'utf-8');
-        console.log(`  ${filename} -> ${pageName}.html`);
-    }
-
-    // Generate placeholder pages for missing wikilink targets
-    const missingTargets = resolver.getMissingTargets();
-    for (const pageName of missingTargets) {
-        const outputPath = path.join(output, pageName + '.html');
-        const nav = buildNav(resolver, pageName);
-        const body = '    <p class="missing-page">This page has not been created yet.</p>';
-        const html = wrapHtml(pageName, nav, body, stylesheets);
-
-        fs.writeFileSync(outputPath, html, 'utf-8');
-        console.log(`  [missing] ${pageName}.html (placeholder)`);
-    }
-
-    const totalFiles = mdFiles.length + missingTargets.size;
-    console.log(`\nConverted ${mdFiles.length} page(s), generated ${missingTargets.size} placeholder(s) -> ${output}`);
-}
-
-main();
diff --git a/html-conversion/.gitignore b/publish/.gitignore
similarity index 100%
rename from html-conversion/.gitignore
rename to publish/.gitignore
diff --git a/publish/README.md b/publish/README.md
new file mode 100644
index 0000000..481a6f2
--- /dev/null
+++ b/publish/README.md
@@ -0,0 +1,6 @@
+# AS Notes Publish
+
+See the following pages for usage instructions:
+
+- <https://github.com/appsoftwareltd/as-notes>
+- <https://www.asnotes.com>
diff --git a/html-conversion/build.mjs b/publish/build.mjs
similarity index 100%
rename from html-conversion/build.mjs
rename to publish/build.mjs
diff --git a/html-conversion/package-lock.json b/publish/package-lock.json
similarity index 99%
rename from html-conversion/package-lock.json
rename to publish/package-lock.json
index 25e694d..efda533 100644
--- a/html-conversion/package-lock.json
+++ b/publish/package-lock.json
@@ -1,22 +1,21 @@
 {
-    "name": "as-notes-html-conversion",
+    "name": "@appsoftwareltd/asnotes-publish",
     "version": "1.0.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
-            "name": "as-notes-html-conversion",
+            "name": "@appsoftwareltd/asnotes-publish",
             "version": "1.0.0",
-            "dependencies": {
-                "as-notes-common": "file:../common",
-                "markdown-it": "^14.1.1"
-            },
+            "license": "Elastic-2.0",
             "bin": {
-                "as-notes-convert": "dist/convert.js"
+                "asnotes-publish": "dist/convert.js"
             },
             "devDependencies": {
                 "@types/node": "^20.11.0",
+                "as-notes-common": "file:../common",
                 "esbuild": "^0.24.0",
+                "markdown-it": "^14.1.1",
                 "typescript": "^5.7.0",
                 "vitest": "^3.0.0"
             }
@@ -24,6 +23,7 @@
         "../common": {
             "name": "as-notes-common",
             "version": "1.0.0",
+            "dev": true,
             "dependencies": {
                 "markdown-it": "^14.1.1"
             },
@@ -922,7 +922,8 @@
         "node_modules/argparse": {
             "version": "2.0.1",
             "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
-            "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="
+            "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+            "dev": true
         },
         "node_modules/as-notes-common": {
             "resolved": "../common",
@@ -1001,6 +1002,7 @@
             "version": "4.5.0",
             "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
             "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+            "dev": true,
             "engines": {
                 "node": ">=0.12"
             },
@@ -1113,6 +1115,7 @@
             "version": "5.0.0",
             "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
             "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
+            "dev": true,
             "dependencies": {
                 "uc.micro": "^2.0.0"
             }
@@ -1136,6 +1139,7 @@
             "version": "14.1.1",
             "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.1.tgz",
             "integrity": "sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==",
+            "dev": true,
             "dependencies": {
                 "argparse": "^2.0.1",
                 "entities": "^4.4.0",
@@ -1151,7 +1155,8 @@
         "node_modules/mdurl": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
-            "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w=="
+            "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
+            "dev": true
         },
         "node_modules/ms": {
             "version": "2.1.3",
@@ -1242,6 +1247,7 @@
             "version": "2.3.1",
             "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
             "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+            "dev": true,
             "engines": {
                 "node": ">=6"
             }
@@ -1400,7 +1406,8 @@
         "node_modules/uc.micro": {
             "version": "2.1.0",
             "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
-            "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A=="
+            "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+            "dev": true
         },
         "node_modules/undici-types": {
             "version": "6.21.0",
diff --git a/publish/package.json b/publish/package.json
new file mode 100644
index 0000000..eb8e3eb
--- /dev/null
+++ b/publish/package.json
@@ -0,0 +1,46 @@
+{
+    "name": "@appsoftwareltd/asnotes-publish",
+    "version": "1.0.2",
+    "description": "Convert AS Notes markdown workspaces (with wikilinks, front matter, and task tags) to static HTML sites",
+    "type": "module",
+    "main": "./dist/convert.js",
+    "bin": {
+        "asnotes-publish": "./dist/convert.js"
+    },
+    "files": [
+        "dist/"
+    ],
+    "scripts": {
+        "build": "node build.mjs",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "tsc --noEmit",
+        "convert": "node dist/convert.js"
+    },
+    "keywords": [
+        "markdown",
+        "wikilinks",
+        "static-site-generator",
+        "notes",
+        "publishing",
+        "html",
+        "as-notes"
+    ],
+    "author": "App Software Ltd",
+    "license": "Elastic-2.0",
+    "homepage": "https://www.asnotes.io",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/appsoftwareltd/as-notes.git",
+        "directory": "publish"
+    },
+    "dependencies": {},
+    "devDependencies": {
+        "@types/node": "^20.11.0",
+        "as-notes-common": "file:../common",
+        "esbuild": "^0.24.0",
+        "markdown-it": "^14.1.1",
+        "typescript": "^5.7.0",
+        "vitest": "^3.0.0"
+    }
+}
\ No newline at end of file
diff --git a/html-conversion/src/FileResolver.ts b/publish/src/FileResolver.ts
similarity index 82%
rename from html-conversion/src/FileResolver.ts
rename to publish/src/FileResolver.ts
index 4bf34c9..64e801c 100644
--- a/html-conversion/src/FileResolver.ts
+++ b/publish/src/FileResolver.ts
@@ -1,8 +1,21 @@
 import type { WikilinkResolverFn } from 'as-notes-common';
 
+export function slugify(name: string): string {
+    return name
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+
 export interface PageEntry {
     name: string;
     href: string;
+    title?: string;
+    order?: number;
+    date?: string;
+    description?: string;
 }
 
 /**
@@ -35,7 +48,7 @@ export class FileResolver {
         const originalName = this.lookup.get(key);
 
         if (originalName) {
-            return encodeURIComponent(originalName).replace(/%2F/gi, '/') + '.html';
+            return slugify(originalName) + '.html';
         }
 
         // Track the missing target (deduplicate by lowercase key, keep first casing)
@@ -43,7 +56,7 @@ export class FileResolver {
             this.missingTargets.set(key, pageFileName);
         }
 
-        return encodeURIComponent(pageFileName).replace(/%2F/gi, '/') + '.html';
+        return slugify(pageFileName) + '.html';
     }
 
     createResolverFn(): WikilinkResolverFn {
@@ -62,7 +75,7 @@ export class FileResolver {
         for (const [_key, name] of this.originalNames) {
             entries.push({
                 name,
-                href: encodeURIComponent(name).replace(/%2F/gi, '/') + '.html',
+                href: slugify(name) + '.html',
             });
         }
 
diff --git a/html-conversion/src/TaskTagPlugin.ts b/publish/src/TaskTagPlugin.ts
similarity index 100%
rename from html-conversion/src/TaskTagPlugin.ts
rename to publish/src/TaskTagPlugin.ts
diff --git a/publish/src/convert.ts b/publish/src/convert.ts
new file mode 100644
index 0000000..a2910f4
--- /dev/null
+++ b/publish/src/convert.ts
@@ -0,0 +1,1554 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import MarkdownIt from 'markdown-it';
+import { WikilinkService, wikilinkPlugin, FrontMatterService, type FrontMatterFields } from 'as-notes-common';
+import { FileResolver, slugify, type PageEntry } from './FileResolver.js';
+import { taskTagPlugin } from './TaskTagPlugin.js';
+
+interface PublishConfig {
+    inputDir?: string;
+    defaultPublic?: boolean;
+    defaultAssets?: boolean;
+    layout?: string;
+    layouts?: string;
+    includes?: string;
+    theme?: string;
+    themes?: string;
+    baseUrl?: string;
+    retina?: boolean;
+    includeDrafts?: boolean;
+    stylesheets?: string[];
+    exclude?: string[];
+    outputDir?: string;
+}
+
+interface CliArgs {
+    input: string;
+    output: string;
+    config: string;
+    stylesheets: string[];
+    assets: string[];
+    exclude: string[];
+    defaultPublic: boolean;
+    defaultAssets: boolean;
+    layout: string;
+    layouts: string;
+    includes: string;
+    theme: string;
+    themes: string;
+    retina: boolean;
+    baseUrl: string;
+    includeDrafts: boolean;
+}
+
+const DEFAULT_EXCLUDES = ['templates', 'node_modules'];
+
+function loadConfigFile(configPath: string): PublishConfig {
+    const resolved = path.resolve(configPath);
+    if (!fs.existsSync(resolved)) {
+        console.error(`Config file not found: ${resolved}`);
+        process.exit(1);
+    }
+    const raw = fs.readFileSync(resolved, 'utf-8');
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            console.error(`Config file must contain a JSON object: ${resolved}`);
+            process.exit(1);
+        }
+        return parsed as PublishConfig;
+    } catch {
+        console.error(`Invalid JSON in config file: ${resolved}`);
+        process.exit(1);
+    }
+}
+
+function parseArgs(argv: string[]): CliArgs {
+    let input = '';
+    let output = '';
+    let config = '';
+    const stylesheets: string[] = [];
+    const assets: string[] = [];
+    const exclude: string[] = [];
+    let defaultPublic = false;
+    let defaultAssets = false;
+    let layout = '';
+    let layouts = '';
+    let includes = '';
+    let theme = '';
+    let themes = '';
+    let retina = false;
+    let baseUrl = '';
+    let includeDrafts = false;
+
+    // Track which flags were explicitly set on the CLI
+    const cliSet = new Set<string>();
+
+    for (let i = 2; i < argv.length; i++) {
+        if (argv[i] === '--input' && i + 1 < argv.length) {
+            input = argv[++i]; cliSet.add('input');
+        } else if (argv[i] === '--output' && i + 1 < argv.length) {
+            output = argv[++i]; cliSet.add('output');
+        } else if (argv[i] === '--config' && i + 1 < argv.length) {
+            config = argv[++i];
+        } else if (argv[i] === '--stylesheet' && i + 1 < argv.length) {
+            stylesheets.push(argv[++i]); cliSet.add('stylesheets');
+        } else if (argv[i] === '--asset' && i + 1 < argv.length) {
+            assets.push(argv[++i]);
+        } else if (argv[i] === '--default-public') {
+            defaultPublic = true; cliSet.add('defaultPublic');
+        } else if (argv[i] === '--default-assets') {
+            defaultAssets = true; cliSet.add('defaultAssets');
+        } else if (argv[i] === '--layout' && i + 1 < argv.length) {
+            layout = argv[++i]; cliSet.add('layout');
+        } else if (argv[i] === '--layouts' && i + 1 < argv.length) {
+            layouts = argv[++i]; cliSet.add('layouts');
+        } else if (argv[i] === '--includes' && i + 1 < argv.length) {
+            includes = argv[++i]; cliSet.add('includes');
+        } else if (argv[i] === '--themes' && i + 1 < argv.length) {
+            themes = argv[++i]; cliSet.add('themes');
+        } else if (argv[i] === '--theme' && i + 1 < argv.length) {
+            theme = argv[++i]; cliSet.add('theme');
+        } else if (argv[i] === '--retina') {
+            retina = true; cliSet.add('retina');
+        } else if (argv[i] === '--base-url' && i + 1 < argv.length) {
+            baseUrl = argv[++i].replace(/\/+$/, ''); cliSet.add('baseUrl');
+        } else if (argv[i] === '--include-drafts') {
+            includeDrafts = true; cliSet.add('includeDrafts');
+        } else if (argv[i] === '--exclude' && i + 1 < argv.length) {
+            exclude.push(argv[++i]); cliSet.add('exclude');
+        }
+    }
+
+    // Merge config file values (CLI flags take precedence)
+    if (config) {
+        const configDir = path.dirname(path.resolve(config));
+        const cfg = loadConfigFile(config);
+
+        if (!cliSet.has('defaultPublic') && cfg.defaultPublic != null) defaultPublic = cfg.defaultPublic;
+        if (!cliSet.has('defaultAssets') && cfg.defaultAssets != null) defaultAssets = cfg.defaultAssets;
+        if (!cliSet.has('layout') && cfg.layout) layout = cfg.layout;
+        if (!cliSet.has('theme') && cfg.theme) theme = cfg.theme;
+        if (!cliSet.has('baseUrl') && cfg.baseUrl != null) baseUrl = String(cfg.baseUrl).replace(/\/+$/, '');
+        if (!cliSet.has('retina') && cfg.retina != null) retina = cfg.retina;
+        if (!cliSet.has('includeDrafts') && cfg.includeDrafts != null) includeDrafts = cfg.includeDrafts;
+        if (!cliSet.has('stylesheets') && Array.isArray(cfg.stylesheets)) {
+            for (const s of cfg.stylesheets) { if (typeof s === 'string') stylesheets.push(s); }
+        }
+        if (!cliSet.has('exclude') && Array.isArray(cfg.exclude)) {
+            for (const e of cfg.exclude) { if (typeof e === 'string') exclude.push(e); }
+        }
+        if (!cliSet.has('layouts') && cfg.layouts) layouts = path.resolve(configDir, cfg.layouts);
+        if (!cliSet.has('themes') && cfg.themes) themes = path.resolve(configDir, cfg.themes);
+        if (!cliSet.has('includes') && cfg.includes) includes = path.resolve(configDir, cfg.includes);
+
+        // Default --input to config's inputDir (resolved relative to config dir), then config file's parent directory
+        if (!input && cfg.inputDir) input = path.resolve(configDir, cfg.inputDir);
+        if (!input) input = configDir;
+        // Default --output from config outputDir (resolved relative to config dir)
+        if (!output && cfg.outputDir) output = path.resolve(configDir, cfg.outputDir);
+    }
+
+    // Apply default layout when neither CLI nor config set it
+    if (!layout) layout = 'docs';
+
+    if (!input || !output) {
+        console.error('Usage: asnotes-publish --input <dir> --output <dir> [options]');
+        console.error('       asnotes-publish --config <file> [options]');
+        console.error('');
+        console.error('Options:');
+        console.error('  --config <file>           Load settings from a JSON config file');
+        console.error('  --stylesheet <url|file>   Add a stylesheet (repeatable)');
+        console.error('  --asset <file>            Copy an asset file to output (repeatable)');
+        console.error('  --default-public          Treat pages as public unless public: false');
+        console.error('  --default-assets          Copy referenced assets unless assets: false');
+        console.error('  --layout <name>           Layout template: docs, blog, minimal (default: docs)');
+        console.error('  --layouts <path>          Directory containing layout template files');
+        console.error('  --includes <path>         Directory for custom headers and footers');
+        console.error('  --theme <name>            Built-in CSS theme name');
+        console.error('  --themes <path>           Directory containing custom theme CSS files');
+        console.error('  --retina                  Enable retina image sizing globally');
+        console.error('  --base-url <prefix>       URL path prefix for links/assets');
+        console.error('  --include-drafts          Include pages with draft: true');
+        console.error('  --exclude <dirname>       Exclude a directory from scanning (repeatable)');
+        console.error('');
+        console.error('When --config is used, --input defaults to the config file\'s directory.');
+        console.error('CLI flags override config file values.');
+        console.error('');
+        console.error('Default excluded directories: ' + DEFAULT_EXCLUDES.join(', '));
+        process.exit(1);
+    }
+
+    return { input: path.resolve(input), output: path.resolve(output), config, stylesheets, assets, exclude, defaultPublic, defaultAssets, layout, layouts, includes, theme, themes, retina, baseUrl, includeDrafts };
+}
+
+interface ScannedFile {
+    /** Path relative to the input root (e.g. 'notes/My Page.md') */
+    relativePath: string;
+    /** Filename only (e.g. 'My Page.md') */
+    filename: string;
+}
+
+function scanMarkdownFiles(dir: string, excludeDirs: string[] = []): ScannedFile[] {
+    const allExcludes = new Set([...DEFAULT_EXCLUDES, ...excludeDirs].map(d => d.toLowerCase()));
+    const results: ScannedFile[] = [];
+
+    function walk(currentDir: string, relativePrefix: string): void {
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!allExcludes.has(entry.name.toLowerCase())) {
+                    walk(path.join(currentDir, entry.name), relativePrefix ? relativePrefix + '/' + entry.name : entry.name);
+                }
+            } else if (entry.isFile() && entry.name.endsWith('.md') && !entry.name.endsWith('.enc.md')) {
+                results.push({
+                    relativePath: relativePrefix ? relativePrefix + '/' + entry.name : entry.name,
+                    filename: entry.name,
+                });
+            }
+        }
+    }
+
+    walk(dir, '');
+    results.sort((a, b) => a.filename.localeCompare(b.filename));
+    return results;
+}
+
+function stripBrackets(text: string): string {
+    return text.replace(/\[\[|\]\]/g, '');
+}
+
+/** Render a page name as wikilink-aware HTML. Names containing [[ ]] are
+ *  rendered through markdown-it so nested wikilinks produce separate <a> tags. */
+function renderPageName(md: MarkdownIt, name: string, baseUrl: string): string {
+    if (!name.includes('[[')) {
+        return escapeHtml(name);
+    }
+    const wikilinkText = `[[${name}]]`;
+    let html = md.renderInline(wikilinkText);
+    if (baseUrl) {
+        html = html.replace(/href="([^"]*\.html(?:#[^"]*)?)"/g, (match, href) => {
+            if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('/')) {
+                return match;
+            }
+            return `href="${baseUrl}/${href}"`;
+        });
+    }
+    return html;
+}
+
+function buildNav(pages: PageEntry[], currentPage: string, baseUrl: string, md?: MarkdownIt): string {
+    const items = pages.map(p => {
+        const isCurrent = p.name === currentPage ? ' class="nav-current"' : '';
+        const rawName = p.name === 'index' ? 'Home' : (p.title || p.name);
+        if (md && rawName.includes('[[')) {
+            const rendered = renderPageName(md, rawName, baseUrl);
+            return `        <li${isCurrent}>${rendered}</li>`;
+        }
+        const href = baseUrl ? baseUrl + '/' + p.href : p.href;
+        return `        <li${isCurrent}><a href="${href}">${escapeHtml(stripBrackets(rawName))}</a></li>`;
+    });
+
+    return `    <nav class="site-nav">\n      <ul>\n${items.join('\n')}\n      </ul>\n    </nav>`;
+}
+
+/**
+ * Load an HTML partial file from the includes directory.
+ * Returns undefined if includesDir is not set or the file does not exist.
+ */
+function loadPartial(includesDir: string | undefined, filename: string): string | undefined {
+    if (!includesDir) return undefined;
+    const partialPath = path.join(includesDir, filename);
+    if (!fs.existsSync(partialPath)) return undefined;
+    return fs.readFileSync(partialPath, 'utf-8');
+}
+
+function wrapHtml(title: string, nav: string, body: string, options: {
+    stylesheets?: string[];
+    description?: string;
+    date?: string;
+    toc?: string;
+    layout?: string;
+    layoutsDir?: string;
+    includesDir?: string;
+    baseUrl?: string;
+} = {}): string {
+    const { stylesheets = [], description, date, toc, layout = 'docs', layoutsDir, includesDir, baseUrl = '' } = options;
+
+    const escapedTitle = escapeHtml(title);
+    const headerPartial = loadPartial(includesDir, 'header.html');
+    const footerPartial = loadPartial(includesDir, 'footer.html');
+
+    const templateVars = {
+        title: escapedTitle, nav, content: body, stylesheets, description, date, toc, baseUrl,
+        header: headerPartial, footer: footerPartial,
+    };
+
+    // Try user-defined layout: layoutsDir first, then includesDir (backwards compat), then built-in
+    if (layoutsDir) {
+        const layoutPath = path.join(layoutsDir, layout + '.html');
+        if (fs.existsSync(layoutPath)) {
+            return applyTemplate(fs.readFileSync(layoutPath, 'utf-8'), templateVars);
+        }
+    }
+    if (includesDir) {
+        const customLayoutPath = path.join(includesDir, layout + '.html');
+        if (fs.existsSync(customLayoutPath)) {
+            return applyTemplate(fs.readFileSync(customLayoutPath, 'utf-8'), templateVars);
+        }
+    }
+
+    // Built-in layouts
+    const builtIn = getBuiltInLayout(layout);
+    return applyTemplate(builtIn, templateVars);
+}
+
+function applyTemplate(template: string, vars: {
+    title: string; nav: string; content: string; stylesheets: string[];
+    description?: string; date?: string; toc?: string; baseUrl: string;
+    header?: string; footer?: string;
+}): string {
+    const linkTags = vars.stylesheets.length > 0
+        ? '\n' + vars.stylesheets.map(s => `    <link rel="stylesheet" href="${escapeHtml(s)}">`).join('\n')
+        : '';
+    const metaDesc = vars.description
+        ? `\n    <meta name="description" content="${escapeHtml(vars.description)}">`
+        : '';
+    const dateHtml = vars.date
+        ? `    <time class="page-date" datetime="${escapeHtml(vars.date)}">${escapeHtml(vars.date)}</time>\n`
+        : '';
+    const tocHtml = vars.toc || '';
+
+    // Process header/footer partials: wrap in semantic elements if content exists, otherwise emit HTML comments
+    let headerHtml: string;
+    if (vars.header) {
+        // Apply token replacement within the partial itself
+        const processedHeader = vars.header
+            .replace(/\{\{base-url\}\}/g, vars.baseUrl)
+            .replace(/\{\{title\}\}/g, vars.title);
+        headerHtml = `<header>\n${processedHeader}\n</header>\n`;
+    } else {
+        headerHtml = '<!-- header -->\n';
+    }
+
+    let footerHtml: string;
+    if (vars.footer) {
+        const processedFooter = vars.footer
+            .replace(/\{\{base-url\}\}/g, vars.baseUrl)
+            .replace(/\{\{title\}\}/g, vars.title);
+        footerHtml = `<footer>\n${processedFooter}\n</footer>\n`;
+    } else {
+        footerHtml = '<!-- footer -->\n';
+    }
+
+    return template
+        .replace(/\{\{title\}\}/g, vars.title)
+        .replace(/\{\{header\}\}/g, headerHtml)
+        .replace(/\{\{nav\}\}/g, vars.nav)
+        .replace(/\{\{content\}\}/g, vars.content)
+        .replace(/\{\{stylesheets\}\}/g, linkTags)
+        .replace(/\{\{meta\}\}/g, metaDesc)
+        .replace(/\{\{date\}\}/g, dateHtml)
+        .replace(/\{\{toc\}\}/g, tocHtml)
+        .replace(/\{\{footer\}\}/g, footerHtml)
+        .replace(/\{\{base-url\}\}/g, vars.baseUrl);
+}
+
+function getBuiltInLayout(name: string): string {
+    switch (name) {
+        case 'blog':
+            return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="blog">
+{{header}}    <article class="blog-post">
+{{date}}{{toc}}
+{{content}}
+    </article>
+{{nav}}{{footer}}</body>
+</html>
+`;
+        case 'minimal':
+            return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="minimal">
+{{header}}    <article>
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
+`;
+        case 'docs':
+        default:
+            return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="docs">
+{{header}}{{nav}}
+    <article class="markdown-body">
+{{toc}}
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
+`;
+    }
+}
+
+function escapeHtml(text: string): string {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+
+interface AssetRef {
+    /** Original src attribute value from HTML */
+    originalRef: string;
+    /** Resolved path relative to output root (used for both HTML rewriting and copy destination) */
+    outputRelPath: string;
+    /** Absolute source path on disk */
+    absSource: string;
+}
+
+/**
+ * Extract image/asset references from rendered HTML, resolving paths relative to
+ * the page's source location. Returns resolved refs suitable for path rewriting and copying.
+ */
+function discoverAssetRefs(html: string, pageRelativePath: string, inputDir: string): AssetRef[] {
+    const refs: AssetRef[] = [];
+    const imgRegex = /<img[^>]+src="([^"]+)"/gi;
+    let match: RegExpExecArray | null;
+    while ((match = imgRegex.exec(html)) !== null) {
+        const src = decodeURIComponent(match[1]);
+        // Skip absolute URLs and data URIs
+        if (src.startsWith('http://') || src.startsWith('https://') || src.startsWith('data:')) {
+            continue;
+        }
+
+        // Resolve absolute source path from the page's directory within the input dir
+        const pageDir = path.dirname(path.join(inputDir, pageRelativePath));
+        const absSource = path.resolve(pageDir, src);
+
+        // Compute output-relative path
+        const relToInput = path.relative(inputDir, absSource);
+        let outputRelPath: string;
+        if (!relToInput.startsWith('..')) {
+            // Asset is within the input directory
+            outputRelPath = relToInput.split(path.sep).join('/');
+        } else {
+            // Asset is outside the input directory: strip leading ../ segments
+            const normalized = relToInput.split(path.sep).join('/');
+            outputRelPath = normalized.replace(/^(\.\.\/)+/, '');
+        }
+
+        refs.push({ originalRef: match[1], outputRelPath, absSource });
+    }
+    return refs;
+}
+
+/** Rewrite asset src attributes in HTML to use resolved output-relative paths. */
+function rewriteAssetPaths(html: string, refs: AssetRef[], baseUrl: string): string {
+    let result = html;
+    for (const ref of refs) {
+        const prefix = baseUrl ? baseUrl + '/' : '';
+        result = result.split(`src="${ref.originalRef}"`).join(`src="${prefix}${ref.outputRelPath}"`);
+    }
+    return result;
+}
+
+/** Copy asset files to output using pre-resolved paths. */
+function copyAssets(assetRefs: AssetRef[], outputDir: string): { copied: number; warnings: string[] } {
+    const warnings: string[] = [];
+    let copied = 0;
+    const seen = new Set<string>();
+
+    for (const ref of assetRefs) {
+        // Dedup by absolute source path
+        if (seen.has(ref.absSource)) continue;
+        seen.add(ref.absSource);
+
+        if (!fs.existsSync(ref.absSource)) {
+            warnings.push(`Referenced asset not found: ${ref.originalRef}`);
+            continue;
+        }
+
+        const destPath = path.join(outputDir, ref.outputRelPath);
+
+        // Ensure destination directory exists
+        const destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir)) {
+            fs.mkdirSync(destDir, { recursive: true });
+        }
+
+        fs.copyFileSync(ref.absSource, destPath);
+        copied++;
+        console.log(`  [asset] ${ref.outputRelPath}`);
+    }
+
+    return { copied, warnings };
+}
+
+/** Generate a table of contents from headings in HTML. */
+function generateToc(html: string): string {
+    const headingRegex = /<h([2-4])[^>]*id="([^"]*)"[^>]*>(.*?)<\/h[2-4]>/gi;
+    const items: { level: number; id: string; text: string }[] = [];
+    let match: RegExpExecArray | null;
+    while ((match = headingRegex.exec(html)) !== null) {
+        items.push({ level: parseInt(match[1]), id: match[2], text: match[3].replace(/<[^>]+>/g, '') });
+    }
+
+    if (items.length === 0) return '';
+
+    const lines = ['    <nav class="toc">', '      <details open>', '        <summary>Contents</summary>', '        <ul>'];
+    for (const item of items) {
+        const indent = '          '.repeat(item.level - 1);
+        lines.push(`${indent}<li><a href="#${item.id}">${escapeHtml(item.text)}</a></li>`);
+    }
+    lines.push('        </ul>', '      </details>', '    </nav>');
+    return lines.join('\n');
+}
+
+/** Auto-add heading IDs for TOC linking. */
+function addHeadingIds(md: MarkdownIt): void {
+    const originalHeadingOpen = md.renderer.rules.heading_open;
+    md.renderer.rules.heading_open = function (tokens, idx, options, env, self) {
+        const token = tokens[idx];
+        // Get the text content from the next inline token
+        const inlineToken = tokens[idx + 1];
+        if (inlineToken && inlineToken.children) {
+            const text = inlineToken.children
+                .filter(t => t.type === 'text' || t.type === 'code_inline')
+                .map(t => t.content)
+                .join('');
+            const id = text.toLowerCase().replace(/[^\w\s-]/g, '').replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+            if (id) {
+                token.attrSet('id', id);
+            }
+        }
+        if (originalHeadingOpen) {
+            return originalHeadingOpen(tokens, idx, options, env, self);
+        }
+        return self.renderToken(tokens, idx, options);
+    };
+}
+
+/** Retina markdown-it plugin: transforms {.retina} attribute on images. */
+function retinaPlugin(md: MarkdownIt, opts: { globalRetina: boolean; pageRetina: boolean }): void {
+    const defaultRender = md.renderer.rules.image || function (tokens, idx, options, _env, self) {
+        return self.renderToken(tokens, idx, options);
+    };
+
+    md.renderer.rules.image = function (tokens, idx, options, env, self) {
+        const token = tokens[idx];
+        const srcAttr = token.attrGet('src') || '';
+        const altText = token.content || '';
+
+        // Check if the alt text or surrounding content contains {.retina}
+        let isRetina = opts.globalRetina || opts.pageRetina;
+
+        // Check for {.retina} marker in alt text
+        if (altText.includes('{.retina}')) {
+            isRetina = true;
+            token.content = altText.replace(/\s*\{\.retina\}\s*/g, '').trim();
+        }
+
+        if (isRetina && isImageFile(srcAttr)) {
+            token.attrSet('class', ((token.attrGet('class') || '') + ' retina').trim());
+        }
+
+        return defaultRender(tokens, idx, options, env, self);
+    };
+}
+
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.bmp', '.tiff', '.ico']);
+
+function isImageFile(src: string): boolean {
+    const ext = path.extname(src).toLowerCase();
+    return IMAGE_EXTENSIONS.has(ext);
+}
+
+/** Generate CSS for retina images. */
+function getRetinaCss(): string {
+    return `
+    img.retina {
+        image-rendering: -webkit-optimize-contrast;
+        image-rendering: crisp-edges;
+    }
+    img.retina[width] {
+        /* When width attribute is present, retina images render at that explicit size */
+    }`;
+}
+
+function generateSitemap(pages: PageEntry[], baseUrl: string): string {
+    const lines = ['<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'];
+    for (const page of pages) {
+        const loc = baseUrl ? `${baseUrl}/${page.href}` : page.href;
+        lines.push('  <url>');
+        lines.push(`    <loc>${escapeXml(loc)}</loc>`);
+        if (page.date) {
+            lines.push(`    <lastmod>${escapeXml(page.date)}</lastmod>`);
+        }
+        lines.push('  </url>');
+    }
+    lines.push('</urlset>');
+    return lines.join('\n');
+}
+
+function generateRssFeed(pages: PageEntry[], baseUrl: string, siteTitle: string): string {
+    const pagesWithDates = pages
+        .filter(p => p.date)
+        .sort((a, b) => (b.date || '').localeCompare(a.date || ''));
+
+    const items = pagesWithDates.map(p => {
+        const link = baseUrl ? `${baseUrl}/${p.href}` : p.href;
+        return `    <item>
+      <title>${escapeXml(p.title || p.name)}</title>
+      <link>${escapeXml(link)}</link>
+      ${p.description ? `<description>${escapeXml(p.description)}</description>` : ''}
+      <pubDate>${escapeXml(p.date || '')}</pubDate>
+    </item>`;
+    });
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escapeXml(siteTitle)}</title>
+    <link>${escapeXml(baseUrl || '/')}</link>
+    <description>${escapeXml(siteTitle)} RSS Feed</description>
+    ${items.join('\n')}
+  </channel>
+</rss>`;
+}
+
+function escapeXml(text: string): string {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+
+function main(): void {
+    const args = parseArgs(process.argv);
+    const { input, output, stylesheets, assets, exclude, defaultPublic, defaultAssets, layout, layouts, includes, theme, themes, retina, baseUrl, includeDrafts } = args;
+    const frontMatterService = new FrontMatterService();
+    const resolvedLayoutsDir = layouts ? path.resolve(layouts) : undefined;
+    const resolvedThemesDir = themes ? path.resolve(themes) : undefined;
+    const resolvedIncludesDir = includes ? path.resolve(includes) : undefined;
+
+    // Wipe output directory
+    if (fs.existsSync(output)) {
+        fs.rmSync(output, { recursive: true, force: true });
+    }
+    fs.mkdirSync(output, { recursive: true });
+
+    // Copy explicit --asset files into output directory
+    for (const assetPath of assets) {
+        const resolvedAsset = path.resolve(assetPath);
+        const assetFilename = path.basename(resolvedAsset);
+        fs.copyFileSync(resolvedAsset, path.join(output, assetFilename));
+        console.log(`  [asset] ${assetFilename}`);
+    }
+
+    // Auto-copy local stylesheets to output (Iteration 4E)
+    const resolvedStylesheets: string[] = [];
+    for (const s of stylesheets) {
+        if (s.startsWith('http://') || s.startsWith('https://')) {
+            resolvedStylesheets.push(s);
+        } else {
+            // Local file - copy to output and reference by filename
+            const resolvedPath = path.resolve(s);
+            if (fs.existsSync(resolvedPath)) {
+                const filename = path.basename(resolvedPath);
+                fs.copyFileSync(resolvedPath, path.join(output, filename));
+                resolvedStylesheets.push((baseUrl ? baseUrl + '/' : '') + filename);
+                console.log(`  [stylesheet] ${filename}`);
+            } else {
+                console.warn(`  [warning] Stylesheet not found: ${s}`);
+                resolvedStylesheets.push(s);
+            }
+        }
+    }
+
+    // Add theme CSS if specified: custom themes directory takes precedence over built-in
+    if (theme) {
+        let themeCss: string | null = null;
+        const themeFile = `theme-${theme}.css`;
+        if (resolvedThemesDir) {
+            const customThemePath = path.join(resolvedThemesDir, `${theme}.css`);
+            if (fs.existsSync(customThemePath)) {
+                themeCss = fs.readFileSync(customThemePath, 'utf-8');
+                console.log(`  [theme] ${themeFile} (custom)`);
+            }
+        }
+        if (!themeCss) {
+            themeCss = getBuiltInThemeCss(theme);
+            if (themeCss) {
+                console.log(`  [theme] ${themeFile}`);
+            }
+        }
+        if (themeCss) {
+            fs.writeFileSync(path.join(output, themeFile), themeCss, 'utf-8');
+            resolvedStylesheets.unshift((baseUrl ? baseUrl + '/' : '') + themeFile);
+        } else {
+            console.log(`  [warning] Unknown theme: ${theme}`);
+        }
+    }
+
+    // Add retina CSS if needed
+    if (retina) {
+        const retinaFile = 'retina.css';
+        fs.writeFileSync(path.join(output, retinaFile), getRetinaCss(), 'utf-8');
+        resolvedStylesheets.push((baseUrl ? baseUrl + '/' : '') + retinaFile);
+    }
+
+    // Scan input for markdown files (recursive, with directory exclusion)
+    const scannedFiles = scanMarkdownFiles(input, exclude)
+        .filter(f => f.filename.toLowerCase() !== 'nav.md'); // nav.md is consumed for navigation, not published
+    if (scannedFiles.length === 0) {
+        console.error(`No .md files found in ${input}`);
+        process.exit(1);
+    }
+
+    // Detect filename collisions from different subdirectories
+    const seenFilenames = new Map<string, string>();
+    for (const f of scannedFiles) {
+        const key = f.filename.toLowerCase();
+        const prev = seenFilenames.get(key);
+        if (prev && prev !== f.relativePath) {
+            console.warn(`  [warning] Filename collision: "${f.relativePath}" and "${prev}" share the same name. The later file will overwrite.`);
+        }
+        seenFilenames.set(key, f.relativePath);
+    }
+
+    // Build a map from page name (filename without .md) to relative path for reading
+    const pageSourcePath = new Map<string, string>();
+    // Flat filenames for FileResolver
+    const flatFilenames: string[] = [];
+
+    // Read front matter for each file and determine public/draft status
+    const pageMetadata = new Map<string, { fields: FrontMatterFields; content: string }>();
+    const publicPages = new Set<string>();
+    const nonPublicPages = new Set<string>();
+
+    for (const scanned of scannedFiles) {
+        const pageName = scanned.filename.replace(/\.md$/i, '');
+        const inputPath = path.join(input, scanned.relativePath);
+        const content = fs.readFileSync(inputPath, 'utf-8');
+        const fields = frontMatterService.parseFrontMatterFields(content);
+
+        pageMetadata.set(pageName, { fields, content });
+        pageSourcePath.set(pageName, scanned.relativePath);
+
+        // Only add to flat filenames if not already present (collision case: last wins)
+        if (!flatFilenames.includes(scanned.filename)) {
+            flatFilenames.push(scanned.filename);
+        }
+
+        // Draft filtering (Iteration 6E)
+        if (fields.draft && !includeDrafts) {
+            nonPublicPages.add(pageName);
+            continue;
+        }
+
+        const isPublic = fields.public !== undefined ? fields.public : defaultPublic;
+        if (isPublic) {
+            publicPages.add(pageName);
+        } else {
+            nonPublicPages.add(pageName);
+        }
+    }
+
+    if (publicPages.size === 0) {
+        console.error('No public pages found. Use front matter `public: true` or pass --default-public.');
+        process.exit(1);
+    }
+
+    // Build resolver from ALL flat filenames (so wikilinks resolve even to non-public pages)
+    const resolver = new FileResolver(flatFilenames);
+
+    // Build navigation from public pages with metadata (Iteration 3)
+    const navPages: PageEntry[] = resolver.listPages()
+        .filter(p => publicPages.has(p.name))
+        .map(p => {
+            const meta = pageMetadata.get(p.name);
+            return {
+                ...p,
+                title: meta?.fields.title,
+                order: meta?.fields.order,
+                date: meta?.fields.date,
+                description: meta?.fields.description,
+            };
+        });
+
+    // Sort nav: ordered pages first (by order value), then unordered alphabetically (Iteration 3B)
+    navPages.sort((a, b) => {
+        // index always first
+        if (a.name === 'index') return -1;
+        if (b.name === 'index') return 1;
+
+        const aHasOrder = a.order !== undefined;
+        const bHasOrder = b.order !== undefined;
+
+        if (aHasOrder && bHasOrder) return a.order! - b.order!;
+        if (aHasOrder && !bHasOrder) return -1;
+        if (!aHasOrder && bHasOrder) return 1;
+
+        // Both unordered: alphabetical by display name
+        const aName = a.title || a.name;
+        const bName = b.title || b.name;
+        return aName.localeCompare(bName);
+    });
+
+    // Auto-generate index page if no index.md exists among public pages (Iteration 11B)
+    const needsAutoIndex = !publicPages.has('index');
+    if (needsAutoIndex) {
+        navPages.unshift({ name: 'index', href: 'index.html', title: 'Home' });
+    }
+
+    // Set up markdown-it with plugins
+    const wikilinkService = new WikilinkService();
+    const md = new MarkdownIt({ html: true });
+    wikilinkPlugin(md, {
+        wikilinkService,
+        resolver: resolver.createResolverFn(),
+    });
+    md.use(taskTagPlugin);
+
+    // Add heading IDs for TOC support (Iteration 6D)
+    addHeadingIds(md);
+
+    // Markdown-it instance for nav rendering (wikilink-aware page names)
+    const navMd = new MarkdownIt({ html: true });
+    wikilinkPlugin(navMd, {
+        wikilinkService,
+        resolver: resolver.createResolverFn(),
+    });
+
+    // Custom navigation from nav.md (Iteration 12J)
+    let customNav: string | undefined;
+    const navMdPath = path.join(input, 'nav.md');
+    if (fs.existsSync(navMdPath)) {
+        const navContent = fs.readFileSync(navMdPath, 'utf-8');
+        let navHtml = navMd.render(frontMatterService.stripFrontMatter(navContent));
+        // Prepend baseUrl to resolved wikilink hrefs (they come out as e.g. "my-page.html")
+        if (baseUrl) {
+            navHtml = navHtml.replace(/href="([^"]*\.html(?:#[^"]*)?)"/g, (match, href) => {
+                // Only rewrite relative hrefs (not absolute URLs)
+                if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('/')) {
+                    return match;
+                }
+                return `href="${baseUrl}/${href}"`;
+            });
+        }
+        customNav = `    <nav class="site-nav">\n${navHtml}    </nav>`;
+        console.log('  [nav] Using custom navigation from nav.md');
+    }
+
+    // Convert only public pages
+    let warningCount = 0;
+    let assetsCopied = 0;
+    const allAssetRefs: AssetRef[] = [];
+
+    for (const pageName of publicPages) {
+        const meta = pageMetadata.get(pageName)!;
+        const outputPath = path.join(output, slugify(pageName) + '.html');
+
+        // Retina: page-level or global (Iteration 5)
+        const pageRetina = meta.fields.retina === true;
+        const effectiveRetina = retina || pageRetina;
+
+        // Apply retina plugin per-page
+        const pageMd = new MarkdownIt({ html: true });
+        wikilinkPlugin(pageMd, {
+            wikilinkService,
+            resolver: resolver.createResolverFn(),
+        });
+        pageMd.use(taskTagPlugin);
+        addHeadingIds(pageMd);
+        retinaPlugin(pageMd, { globalRetina: retina, pageRetina });
+
+        // Strip front matter before rendering
+        const strippedMarkdown = frontMatterService.stripFrontMatter(meta.content);
+        let htmlBody = pageMd.render(strippedMarkdown);
+
+        // Asset discovery, path rewriting, and copying (Iteration 2, 12J)
+        const assetsEnabled = meta.fields.assets !== undefined ? meta.fields.assets : defaultAssets;
+        if (assetsEnabled) {
+            const pageRelPath = pageSourcePath.get(pageName) || pageName + '.md';
+            const refs = discoverAssetRefs(htmlBody, pageRelPath, input);
+            htmlBody = rewriteAssetPaths(htmlBody, refs, baseUrl);
+            allAssetRefs.push(...refs);
+        }
+
+        // Prepend baseUrl to wikilink hrefs in article body (Iteration 12O)
+        if (baseUrl) {
+            htmlBody = htmlBody.replace(/href="([^"]*\.html(?:#[^"]*)?)"/g, (match, href) => {
+                if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('/')) {
+                    return match;
+                }
+                return `href="${baseUrl}/${href}"`;
+            });
+        }
+
+        // Check for links to non-public pages and log warnings
+        for (const npPage of nonPublicPages) {
+            const href = resolver.resolve(npPage);
+            if (htmlBody.includes(`href="${href}"`)) {
+                console.warn(`  [warning] ${pageName} links to non-public page "${npPage}" (dead link)`);
+                warningCount++;
+            }
+        }
+
+        // Title from front matter or filename (Iteration 3A, 12F: strip brackets)
+        const title = meta.fields.title
+            ? stripBrackets(meta.fields.title)
+            : (pageName === 'index' ? 'Home' : stripBrackets(pageName));
+
+        // Per-page layout override (Iteration 4C)
+        const pageLayout = meta.fields.layout || layout;
+
+        // Generate TOC (Iteration 6D)
+        const toc = generateToc(htmlBody);
+
+        const nav = customNav ?? buildNav(navPages, pageName, baseUrl, navMd);
+        const html = wrapHtml(title, nav, htmlBody, {
+            stylesheets: resolvedStylesheets,
+            description: meta.fields.description,
+            date: meta.fields.date,
+            toc,
+            layout: pageLayout,
+            layoutsDir: resolvedLayoutsDir,
+            includesDir: resolvedIncludesDir,
+            baseUrl,
+        });
+
+        fs.writeFileSync(outputPath, html, 'utf-8');
+        console.log(`  ${pageName}.md -> ${slugify(pageName)}.html`);
+    }
+
+    // Copy discovered assets (Iteration 2, 12J: resolved paths)
+    if (allAssetRefs.length > 0) {
+        const result = copyAssets(allAssetRefs, output);
+        assetsCopied = result.copied;
+        for (const w of result.warnings) {
+            console.log(`  [warning] ${w}`);
+            warningCount++;
+        }
+    }
+
+    // Generate placeholder pages for missing wikilink targets (excluding non-public pages)
+    const missingTargets = resolver.getMissingTargets();
+
+    // Auto-generate index.html if no index.md was found (Iteration 11B)
+    // Generate as direct HTML to handle page names with brackets cleanly (Iteration 12F)
+    if (needsAutoIndex) {
+        const indexItems = navPages
+            .filter(p => p.name !== 'index')
+            .map(p => {
+                const rawName = p.title || p.name;
+                if (rawName.includes('[[')) {
+                    const rendered = renderPageName(navMd, rawName, baseUrl);
+                    return `<li>${rendered}</li>`;
+                }
+                const href = baseUrl ? baseUrl + '/' + p.href : p.href;
+                return `<li><a href="${href}">${escapeHtml(stripBrackets(rawName))}</a></li>`;
+            });
+        const indexBody = `<h1 id="home">Home</h1>\n<ul>\n${indexItems.join('\n')}\n</ul>`;
+        const indexToc = generateToc(indexBody);
+
+        const nav = customNav ?? buildNav(navPages, 'index', baseUrl, navMd);
+        const indexHtml = wrapHtml('Home', nav, indexBody, {
+            stylesheets: resolvedStylesheets,
+            toc: indexToc,
+            layout,
+            layoutsDir: resolvedLayoutsDir,
+            includesDir: resolvedIncludesDir,
+            baseUrl,
+        });
+        fs.writeFileSync(path.join(output, 'index.html'), indexHtml, 'utf-8');
+        console.log('  [info] No index.md found - generating page index');
+    }
+    for (const pageName of missingTargets) {
+        if (nonPublicPages.has(pageName) || flatFilenames.some(f => f.replace(/\.md$/i, '').toLowerCase() === pageName.toLowerCase() && nonPublicPages.has(f.replace(/\.md$/i, '')))) {
+            continue;
+        }
+
+        const outputPath = path.join(output, slugify(pageName) + '.html');
+        const nav = customNav ?? buildNav(navPages, pageName, baseUrl, navMd);
+        const body = '    <p class="missing-page">This page has not been created yet.</p>';
+        const html = wrapHtml(stripBrackets(pageName), nav, body, { stylesheets: resolvedStylesheets, layout, layoutsDir: resolvedLayoutsDir, includesDir: resolvedIncludesDir, baseUrl });
+
+        fs.writeFileSync(outputPath, html, 'utf-8');
+        console.log(`  [missing] ${slugify(pageName)}.html (placeholder)`);
+    }
+
+    // Generate sitemap.xml (Iteration 6B)
+    const sitemapXml = generateSitemap(navPages, baseUrl);
+    fs.writeFileSync(path.join(output, 'sitemap.xml'), sitemapXml, 'utf-8');
+    console.log('  [sitemap] sitemap.xml');
+
+    // Generate RSS feed (Iteration 6C)
+    const rssFeed = generateRssFeed(navPages, baseUrl, 'AS Notes Site');
+    fs.writeFileSync(path.join(output, 'feed.xml'), rssFeed, 'utf-8');
+    console.log('  [rss] feed.xml');
+
+    const totalFiles = publicPages.size;
+    const placeholders = [...missingTargets].filter(t => !nonPublicPages.has(t)).length;
+    console.log(`\nConverted ${totalFiles} page(s), generated ${placeholders} placeholder(s) -> ${output}`);
+    if (assetsCopied > 0) {
+        console.log(`Copied ${assetsCopied} asset(s)`);
+    }
+    if (nonPublicPages.size > 0) {
+        console.log(`Skipped ${nonPublicPages.size} non-public page(s)`);
+    }
+    if (warningCount > 0) {
+        console.log(`${warningCount} warning(s)`);
+    }
+}
+
+function getBuiltInThemeCss(name: string): string | null {
+    switch (name) {
+        case 'default':
+            return `/* AS Notes default theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #24292e;
+    background: #ffffff;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #f6f8fa;
+    border-bottom: 1px solid #d0d7de;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #24292e;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #0366d6;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #d0d7de;
+    background: #f6f8fa;
+    font-size: 0.85rem;
+    color: #586069;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #0366d6;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #f6f8fa;
+    border-right: 1px solid #d0d7de;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #24292f;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #eaeef2;
+}
+
+.site-nav ul li:hover a {
+    color: #0550ae;
+}
+
+.site-nav ul li.nav-current {
+    background: #ddf4ff;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #0550ae;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+}
+
+a {
+    color: #0366d6;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #f6f8fa;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #f6f8fa;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #f6f8fa;
+    border: 1px solid #e1e4e8;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #586069;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #cb2431;
+    font-style: italic;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #d0d7de;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
+`;
+        case 'dark':
+            return `/* AS Notes dark theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #c9d1d9;
+    background: #0d1117;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #161b22;
+    border-bottom: 1px solid #30363d;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #c9d1d9;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #58a6ff;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #30363d;
+    background: #161b22;
+    font-size: 0.85rem;
+    color: #8b949e;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #58a6ff;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #161b22;
+    border-right: 1px solid #30363d;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #c9d1d9;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #1f2937;
+}
+
+.site-nav ul li:hover a {
+    color: #58a6ff;
+}
+
+.site-nav ul li.nav-current {
+    background: #1f2937;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #58a6ff;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+    color: #f0f6fc;
+}
+
+a {
+    color: #58a6ff;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #161b22;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #161b22;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+    color: #f0f6fc;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #8b949e;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #f85149;
+    font-style: italic;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #30363d;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
+`;
+        default:
+            return null;
+    }
+}
+
+main();
diff --git a/html-conversion/test/FileResolver.test.ts b/publish/test/FileResolver.test.ts
similarity index 60%
rename from html-conversion/test/FileResolver.test.ts
rename to publish/test/FileResolver.test.ts
index 3b07dac..13af24b 100644
--- a/html-conversion/test/FileResolver.test.ts
+++ b/publish/test/FileResolver.test.ts
@@ -1,11 +1,49 @@
 import { describe, it, expect } from 'vitest';
-import { FileResolver } from '../src/FileResolver.js';
+import { FileResolver, slugify } from '../src/FileResolver.js';
+
+describe('slugify', () => {
+    it('should lowercase and hyphenate', () => {
+        expect(slugify('My Cool Page')).toBe('my-cool-page');
+    });
+
+    it('should handle underscores', () => {
+        expect(slugify('my_page_name')).toBe('my-page-name');
+    });
+
+    it('should remove special characters', () => {
+        expect(slugify('Page & Notes!')).toBe('page-notes');
+    });
+
+    it('should collapse consecutive hyphens', () => {
+        expect(slugify('Page -- Something')).toBe('page-something');
+    });
+
+    it('should trim leading/trailing hyphens', () => {
+        expect(slugify('-Leading-')).toBe('leading');
+    });
+
+    it('should keep index as index', () => {
+        expect(slugify('index')).toBe('index');
+    });
+
+    it('should handle already-slugified names', () => {
+        expect(slugify('my-page')).toBe('my-page');
+    });
+
+    it('should handle names with numbers', () => {
+        expect(slugify('Chapter 1 Introduction')).toBe('chapter-1-introduction');
+    });
+
+    it('should handle mixed case', () => {
+        expect(slugify('Getting Started')).toBe('getting-started');
+    });
+});
 
 describe('FileResolver', () => {
     describe('basic resolution', () => {
-        it('should resolve a page name to its .html href', () => {
+        it('should resolve a page name to its slugified .html href', () => {
             const resolver = new FileResolver(['index.md', 'Wikilinks.md']);
-            expect(resolver.resolve('Wikilinks')).toBe('Wikilinks.html');
+            expect(resolver.resolve('Wikilinks')).toBe('wikilinks.html');
         });
 
         it('should resolve index page', () => {
@@ -13,33 +51,33 @@ describe('FileResolver', () => {
             expect(resolver.resolve('index')).toBe('index.html');
         });
 
-        it('should return a valid .html href for missing targets', () => {
+        it('should return a slugified .html href for missing targets', () => {
             const resolver = new FileResolver(['index.md']);
-            expect(resolver.resolve('NonExistent')).toBe('NonExistent.html');
+            expect(resolver.resolve('NonExistent')).toBe('nonexistent.html');
         });
     });
 
     describe('case-insensitive matching', () => {
         it('should resolve case-insensitively', () => {
             const resolver = new FileResolver(['Wikilinks.md']);
-            expect(resolver.resolve('wikilinks')).toBe('Wikilinks.html');
+            expect(resolver.resolve('wikilinks')).toBe('wikilinks.html');
         });
 
-        it('should resolve uppercase input to original filename casing', () => {
+        it('should resolve uppercase input to slugified href', () => {
             const resolver = new FileResolver(['Wikilinks.md']);
-            expect(resolver.resolve('WIKILINKS')).toBe('Wikilinks.html');
+            expect(resolver.resolve('WIKILINKS')).toBe('wikilinks.html');
         });
     });
 
-    describe('URL encoding', () => {
-        it('should URL-encode spaces in page names', () => {
+    describe('slug formatting', () => {
+        it('should slugify spaces in page names', () => {
             const resolver = new FileResolver(['My Page.md']);
-            expect(resolver.resolve('My Page')).toBe('My%20Page.html');
+            expect(resolver.resolve('My Page')).toBe('my-page.html');
         });
 
-        it('should URL-encode special characters', () => {
+        it('should slugify special characters', () => {
             const resolver = new FileResolver(['Page & Notes.md']);
-            expect(resolver.resolve('Page & Notes')).toBe('Page%20%26%20Notes.html');
+            expect(resolver.resolve('Page & Notes')).toBe('page-notes.html');
         });
     });
 
@@ -47,13 +85,13 @@ describe('FileResolver', () => {
         it('should work as a WikilinkResolverFn via createResolverFn', () => {
             const resolver = new FileResolver(['index.md', 'Topics.md']);
             const resolverFn = resolver.createResolverFn();
-            expect(resolverFn('Topics', {})).toBe('Topics.html');
+            expect(resolverFn('Topics', {})).toBe('topics.html');
         });
 
         it('should handle missing pages in resolver fn', () => {
             const resolver = new FileResolver(['index.md']);
             const resolverFn = resolver.createResolverFn();
-            expect(resolverFn('Missing', {})).toBe('Missing.html');
+            expect(resolverFn('Missing', {})).toBe('missing.html');
         });
     });
 
@@ -63,8 +101,8 @@ describe('FileResolver', () => {
             const pages = resolver.listPages();
             expect(pages).toEqual([
                 { name: 'index', href: 'index.html' },
-                { name: 'Getting Started', href: 'Getting%20Started.html' },
-                { name: 'Wikilinks', href: 'Wikilinks.html' },
+                { name: 'Getting Started', href: 'getting-started.html' },
+                { name: 'Wikilinks', href: 'wikilinks.html' },
             ]);
         });
 
@@ -98,9 +136,9 @@ describe('FileResolver', () => {
             expect(resolver.getMissingTargets()).toEqual(new Set(['Missing']));
         });
 
-        it('should URL-encode missing target hrefs', () => {
+        it('should slugify missing target hrefs', () => {
             const resolver = new FileResolver(['index.md']);
-            expect(resolver.resolve('Missing Page')).toBe('Missing%20Page.html');
+            expect(resolver.resolve('Missing Page')).toBe('missing-page.html');
             expect(resolver.getMissingTargets()).toEqual(new Set(['Missing Page']));
         });
 
diff --git a/html-conversion/test/TaskTagPlugin.test.ts b/publish/test/TaskTagPlugin.test.ts
similarity index 100%
rename from html-conversion/test/TaskTagPlugin.test.ts
rename to publish/test/TaskTagPlugin.test.ts
diff --git a/publish/test/config.test.ts b/publish/test/config.test.ts
new file mode 100644
index 0000000..2f06d85
--- /dev/null
+++ b/publish/test/config.test.ts
@@ -0,0 +1,760 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execFileSync } from 'child_process';
+
+const CLI = path.resolve(__dirname, '..', 'dist', 'convert.js');
+
+function run(args: string[]): string {
+    return execFileSync('node', [CLI, ...args], {
+        encoding: 'utf-8',
+        timeout: 15000,
+    });
+}
+
+function runExpectError(args: string[]): string {
+    try {
+        execFileSync('node', [CLI, ...args], {
+            encoding: 'utf-8',
+            timeout: 15000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        throw new Error('Expected process to exit with error');
+    } catch (err: unknown) {
+        const e = err as { stderr?: string; status?: number };
+        return e.stderr ?? '';
+    }
+}
+
+describe('--config flag', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+    let configPath: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-config-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        configPath = path.join(tmpDir, 'asnotes-publish.json');
+        fs.mkdirSync(inputDir, { recursive: true });
+        // Create a simple test page
+        fs.writeFileSync(
+            path.join(inputDir, 'Hello.md'),
+            '---\npublic: true\n---\n# Hello World\n',
+        );
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should load config file and use its settings', () => {
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            defaultAssets: true,
+            layout: 'blog',
+            outputDir: './site',
+        }));
+        // --config + --input: config provides outputDir, layout
+        const output = run(['--config', configPath, '--input', inputDir]);
+        expect(output).toContain('Hello');
+        expect(fs.existsSync(path.join(outputDir, 'hello.html'))).toBe(true);
+        // Verify blog layout was used
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('blog-post');
+    });
+
+    it('should default --input to config file parent directory', () => {
+        // Put the config in the notes dir itself
+        const cfgInNotes = path.join(inputDir, 'asnotes-publish.json');
+        fs.writeFileSync(cfgInNotes, JSON.stringify({
+            defaultPublic: true,
+            outputDir: path.resolve(outputDir),
+        }));
+        // No --input flag: should default to inputDir (config file's directory)
+        const output = run(['--config', cfgInNotes]);
+        expect(output).toContain('Hello');
+        expect(fs.existsSync(path.join(outputDir, 'hello.html'))).toBe(true);
+    });
+
+    it('should default --output from config outputDir resolved relative to config dir', () => {
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            outputDir: './site',
+        }));
+        // --input from CLI, --output from config (relative to config dir = tmpDir)
+        const output = run(['--config', configPath, '--input', inputDir]);
+        expect(output).toContain('Hello');
+        expect(fs.existsSync(path.join(tmpDir, 'site', 'hello.html'))).toBe(true);
+    });
+
+    it('CLI flags should override config values', () => {
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            layout: 'blog',
+            outputDir: './site',
+        }));
+        // Override layout via CLI
+        const output = run(['--config', configPath, '--input', inputDir, '--layout', 'minimal']);
+        expect(fs.existsSync(path.join(outputDir, 'hello.html'))).toBe(true);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        // minimal layout has no nav and no special article class
+        expect(html).not.toContain('blog-post');
+        expect(html).not.toContain('site-nav');
+    });
+
+    it('CLI --output should override config outputDir', () => {
+        const altOutput = path.join(tmpDir, 'alt-output');
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            outputDir: './site',
+        }));
+        run(['--config', configPath, '--input', inputDir, '--output', altOutput]);
+        expect(fs.existsSync(path.join(altOutput, 'hello.html'))).toBe(true);
+        // Config's outputDir should NOT be created
+        expect(fs.existsSync(outputDir)).toBe(false);
+    });
+
+    it('should load stylesheets and exclude from config', () => {
+        // Create a subdirectory with a note that should be excluded
+        const draftsDir = path.join(inputDir, 'drafts');
+        fs.mkdirSync(draftsDir);
+        fs.writeFileSync(
+            path.join(draftsDir, 'Secret.md'),
+            '---\npublic: true\n---\n# Secret\n',
+        );
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            exclude: ['drafts'],
+            outputDir: './site',
+        }));
+        const output = run(['--config', configPath, '--input', inputDir]);
+        expect(output).toContain('Hello');
+        // Secret should NOT be in the output (excluded)
+        expect(fs.existsSync(path.join(outputDir, 'secret.html'))).toBe(false);
+    });
+
+    it('should error on missing config file', () => {
+        const stderr = runExpectError(['--config', path.join(tmpDir, 'nonexistent.json')]);
+        expect(stderr).toContain('Config file not found');
+    });
+
+    it('should error on invalid JSON in config file', () => {
+        fs.writeFileSync(configPath, 'not json');
+        const stderr = runExpectError([
+            '--config', configPath,
+            '--input', inputDir,
+            '--output', outputDir,
+        ]);
+        expect(stderr).toContain('Invalid JSON');
+    });
+
+    it('should still work without --config (backward compatible)', () => {
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(output).toContain('Hello');
+        expect(fs.existsSync(path.join(outputDir, 'hello.html'))).toBe(true);
+    });
+
+    it('should load includes directory from config', () => {
+        const includesDir = path.join(tmpDir, 'includes');
+        fs.mkdirSync(includesDir, { recursive: true });
+        fs.writeFileSync(path.join(includesDir, 'header.html'), '<div class="my-header">Site Header</div>');
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            includes: './includes',
+            outputDir: './site',
+        }));
+        run(['--config', configPath, '--input', inputDir]);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('<header>');
+        expect(html).toContain('my-header');
+        expect(html).toContain('Site Header');
+    });
+
+    it('CLI --includes should override config includes', () => {
+        const includesDir1 = path.join(tmpDir, 'inc1');
+        const includesDir2 = path.join(tmpDir, 'inc2');
+        fs.mkdirSync(includesDir1, { recursive: true });
+        fs.mkdirSync(includesDir2, { recursive: true });
+        fs.writeFileSync(path.join(includesDir1, 'header.html'), '<div>Header One</div>');
+        fs.writeFileSync(path.join(includesDir2, 'header.html'), '<div>Header Two</div>');
+        fs.writeFileSync(configPath, JSON.stringify({
+            defaultPublic: true,
+            includes: './inc1',
+            outputDir: './site',
+        }));
+        run(['--config', configPath, '--input', inputDir, '--includes', includesDir2]);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('Header Two');
+        expect(html).not.toContain('Header One');
+    });
+});
+
+describe('auto-generated index page', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-index-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        fs.mkdirSync(inputDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should auto-generate index.html when no index.md exists', () => {
+        fs.writeFileSync(path.join(inputDir, 'About.md'), '---\npublic: true\n---\n# About\n');
+        fs.writeFileSync(path.join(inputDir, 'Contact.md'), '---\npublic: true\n---\n# Contact\n');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(output).toContain('No index.md found');
+        expect(fs.existsSync(path.join(outputDir, 'index.html'))).toBe(true);
+        const html = fs.readFileSync(path.join(outputDir, 'index.html'), 'utf-8');
+        // Links should point to correct pages
+        expect(html).toContain('href="about.html"');
+        expect(html).toContain('href="contact.html"');
+        expect(html).toContain('About');
+        expect(html).toContain('Contact');
+        expect(html).toContain('<title>Home</title>');
+    });
+
+    it('should use existing index.md when present', () => {
+        fs.writeFileSync(path.join(inputDir, 'index.md'), '---\npublic: true\ntitle: Welcome\n---\n# My Home Page\n');
+        fs.writeFileSync(path.join(inputDir, 'About.md'), '---\npublic: true\n---\n# About\n');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(output).not.toContain('No index.md found');
+        expect(fs.existsSync(path.join(outputDir, 'index.html'))).toBe(true);
+        const html = fs.readFileSync(path.join(outputDir, 'index.html'), 'utf-8');
+        expect(html).toContain('My Home Page');
+        expect(html).toContain('<title>Welcome</title>');
+    });
+
+    it('auto-generated index should include Home in navigation', () => {
+        fs.writeFileSync(path.join(inputDir, 'Page1.md'), '---\npublic: true\n---\n# Page 1\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        const html = fs.readFileSync(path.join(outputDir, 'index.html'), 'utf-8');
+        // Nav should include Home link for the auto-generated index
+        expect(html).toContain('Home');
+        expect(html).toContain('index.html');
+    });
+
+    it('should render nested wikilinks as separate links in auto-generated nav', () => {
+        fs.writeFileSync(path.join(inputDir, 'Plant.md'), '---\npublic: true\n---\n# Plant\n');
+        fs.writeFileSync(path.join(inputDir, '[[Plant]] Foods.md'), '---\npublic: true\n---\n# Plant Foods\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        const html = fs.readFileSync(path.join(outputDir, 'plant.html'), 'utf-8');
+        const nav = html.match(/<nav[^>]*>([\s\S]*?)<\/nav>/)?.[1] || '';
+        // The nav item for "[[Plant]] Foods" should contain two separate <a> tags
+        expect(nav).toContain('href="plant.html"');
+        expect(nav).toContain('href="plant-foods.html"');
+        // Both links should be in the same <li>
+        const plantFoodsLi = nav.match(/<li[^>]*>.*?plant-foods\.html.*?<\/li>/s)?.[0] || '';
+        expect(plantFoodsLi).toContain('href="plant.html"');
+        expect(plantFoodsLi).toContain('href="plant-foods.html"');
+    });
+
+    it('should render nested wikilinks as separate links in auto-generated index', () => {
+        fs.writeFileSync(path.join(inputDir, 'Plant.md'), '---\npublic: true\n---\n# Plant\n');
+        fs.writeFileSync(path.join(inputDir, '[[Plant]] Foods.md'), '---\npublic: true\n---\n# Plant Foods\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        const html = fs.readFileSync(path.join(outputDir, 'index.html'), 'utf-8');
+        const article = html.match(/<article[^>]*>([\s\S]*?)<\/article>/)?.[1] || '';
+        // Index listing for "[[Plant]] Foods" should have two separate links
+        const plantFoodsLi = article.match(/<li[^>]*>.*?plant-foods\.html.*?<\/li>/s)?.[0] || '';
+        expect(plantFoodsLi).toContain('href="plant.html"');
+        expect(plantFoodsLi).toContain('href="plant-foods.html"');
+    });
+});
+
+describe('.enc.md exclusion', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-enc-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        fs.mkdirSync(inputDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should exclude .enc.md files from published output', () => {
+        fs.writeFileSync(path.join(inputDir, 'Public.md'), '---\npublic: true\n---\n# Public Page\n');
+        fs.writeFileSync(path.join(inputDir, 'Secret.enc.md'), '---\npublic: true\n---\n# Secret Note\n');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(output).toContain('Public');
+        expect(output).not.toContain('Secret');
+        expect(fs.existsSync(path.join(outputDir, 'public.html'))).toBe(true);
+        expect(fs.existsSync(path.join(outputDir, 'secret.html'))).toBe(false);
+        expect(fs.existsSync(path.join(outputDir, 'secret-enc.html'))).toBe(false);
+    });
+
+    it('should exclude .enc.md files even with --default-public', () => {
+        fs.writeFileSync(path.join(inputDir, 'Normal.md'), '# Normal\n');
+        fs.writeFileSync(path.join(inputDir, 'Encrypted.enc.md'), '# Encrypted\n');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(output).toContain('Normal');
+        expect(output).not.toContain('Encrypted');
+    });
+
+    it('should exclude .enc.md files in subdirectories', () => {
+        const subDir = path.join(inputDir, 'private');
+        fs.mkdirSync(subDir, { recursive: true });
+        fs.writeFileSync(path.join(inputDir, 'Public.md'), '---\npublic: true\n---\n# Public\n');
+        fs.writeFileSync(path.join(subDir, 'Deep.enc.md'), '---\npublic: true\n---\n# Deep Secret\n');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(output).toContain('Public');
+        expect(output).not.toContain('Deep');
+    });
+});
+
+describe('--layouts flag', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+    let layoutsDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-layouts-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        layoutsDir = path.join(tmpDir, 'layouts');
+        fs.mkdirSync(inputDir, { recursive: true });
+        fs.mkdirSync(layoutsDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should use custom layout from layouts directory', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        fs.writeFileSync(path.join(layoutsDir, 'docs.html'), '<html><body class="custom-layout">{{content}}</body></html>');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public', '--layouts', layoutsDir]);
+        expect(output).toContain('Hello');
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('custom-layout');
+    });
+
+    it('should fall back to built-in layout when layouts directory has no matching file', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        // layoutsDir exists but has no docs.html
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public', '--layouts', layoutsDir]);
+        expect(output).toContain('Hello');
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('markdown-body');
+    });
+
+    it('should load layouts from config file', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        fs.writeFileSync(path.join(layoutsDir, 'blog.html'), '<html><body class="my-blog">{{content}}</body></html>');
+        const configPath = path.join(tmpDir, 'asnotes-publish.json');
+        fs.writeFileSync(configPath, JSON.stringify({
+            inputDir: './notes',
+            outputDir: './site',
+            defaultPublic: true,
+            layout: 'blog',
+            layouts: './layouts',
+        }));
+        const output = run(['--config', configPath]);
+        expect(output).toContain('Hello');
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('my-blog');
+    });
+
+    it('should prefer layouts directory over includes directory for layout files', () => {
+        const includesDir = path.join(tmpDir, 'includes');
+        fs.mkdirSync(includesDir, { recursive: true });
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        fs.writeFileSync(path.join(layoutsDir, 'docs.html'), '<html><body class="from-layouts">{{content}}</body></html>');
+        fs.writeFileSync(path.join(includesDir, 'docs.html'), '<html><body class="from-includes">{{content}}</body></html>');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public', '--layouts', layoutsDir, '--includes', includesDir]);
+        expect(output).toContain('Hello');
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('from-layouts');
+        expect(html).not.toContain('from-includes');
+    });
+});
+
+describe('data-layout attribute', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-data-layout-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        fs.mkdirSync(inputDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should add data-layout="docs" to body for docs layout', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--layout', 'docs']);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('data-layout="docs"');
+    });
+
+    it('should add data-layout="blog" to body for blog layout', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--layout', 'blog']);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('data-layout="blog"');
+    });
+
+    it('should add data-layout="minimal" to body for minimal layout', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--layout', 'minimal']);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        expect(html).toContain('data-layout="minimal"');
+    });
+
+    it('should place nav after article in blog layout', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        fs.writeFileSync(path.join(inputDir, 'World.md'), '---\npublic: true\n---\n# World\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--layout', 'blog']);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        const articleEnd = html.indexOf('</article>');
+        const navStart = html.indexOf('<nav');
+        expect(articleEnd).toBeGreaterThan(-1);
+        expect(navStart).toBeGreaterThan(-1);
+        expect(navStart).toBeGreaterThan(articleEnd);
+    });
+
+    it('should place nav before article in docs layout', () => {
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+        fs.writeFileSync(path.join(inputDir, 'World.md'), '---\npublic: true\n---\n# World\n');
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--layout', 'docs']);
+        const html = fs.readFileSync(path.join(outputDir, 'hello.html'), 'utf-8');
+        const articleStart = html.indexOf('<article');
+        const navStart = html.indexOf('<nav');
+        expect(articleStart).toBeGreaterThan(-1);
+        expect(navStart).toBeGreaterThan(-1);
+        expect(navStart).toBeLessThan(articleStart);
+    });
+});
+
+describe('asset path resolution', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-asset-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        fs.mkdirSync(inputDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should copy assets referenced by same-directory images', () => {
+        fs.writeFileSync(path.join(inputDir, 'photo.png'), 'PNG_DATA');
+        fs.writeFileSync(
+            path.join(inputDir, 'Page.md'),
+            '---\npublic: true\nassets: true\n---\n# Page\n\n![Image](photo.png)\n',
+        );
+        run(['--input', inputDir, '--output', outputDir]);
+        expect(fs.existsSync(path.join(outputDir, 'photo.png'))).toBe(true);
+        const html = fs.readFileSync(path.join(outputDir, 'page.html'), 'utf-8');
+        expect(html).toContain('src="photo.png"');
+    });
+
+    it('should copy assets in subdirectories and rewrite paths', () => {
+        const imgDir = path.join(inputDir, 'images');
+        fs.mkdirSync(imgDir, { recursive: true });
+        fs.writeFileSync(path.join(imgDir, 'pic.png'), 'PNG_DATA');
+        fs.writeFileSync(
+            path.join(inputDir, 'Page.md'),
+            '---\npublic: true\nassets: true\n---\n# Page\n\n![Image](images/pic.png)\n',
+        );
+        run(['--input', inputDir, '--output', outputDir]);
+        expect(fs.existsSync(path.join(outputDir, 'images', 'pic.png'))).toBe(true);
+        const html = fs.readFileSync(path.join(outputDir, 'page.html'), 'utf-8');
+        expect(html).toContain('src="images/pic.png"');
+    });
+
+    it('should copy assets referenced with ../ paths outside input dir', () => {
+        // Input is a subdirectory; assets are at the parent level
+        const pagesDir = path.join(tmpDir, 'docs', 'pages');
+        const assetsDir = path.join(tmpDir, 'docs', 'assets', 'images');
+        const outDir = path.join(tmpDir, 'out');
+        fs.mkdirSync(pagesDir, { recursive: true });
+        fs.mkdirSync(assetsDir, { recursive: true });
+        fs.writeFileSync(path.join(assetsDir, 'screenshot.png'), 'PNG_DATA');
+        fs.writeFileSync(
+            path.join(pagesDir, 'index.md'),
+            '---\npublic: true\nassets: true\n---\n# Home\n\n![Screenshot](../assets/images/screenshot.png)\n',
+        );
+        run(['--input', pagesDir, '--output', outDir]);
+        // Asset should be copied into output (leading ../ stripped)
+        expect(fs.existsSync(path.join(outDir, 'assets', 'images', 'screenshot.png'))).toBe(true);
+        const html = fs.readFileSync(path.join(outDir, 'index.html'), 'utf-8');
+        expect(html).toContain('src="assets/images/screenshot.png"');
+    });
+
+    it('should copy assets from pages in subdirectories', () => {
+        const subDir = path.join(inputDir, 'guides');
+        const imgDir = path.join(inputDir, 'images');
+        fs.mkdirSync(subDir, { recursive: true });
+        fs.mkdirSync(imgDir, { recursive: true });
+        fs.writeFileSync(path.join(imgDir, 'help.png'), 'PNG_DATA');
+        fs.writeFileSync(
+            path.join(subDir, 'Tutorial.md'),
+            '---\npublic: true\nassets: true\n---\n# Tutorial\n\n![Help](../images/help.png)\n',
+        );
+        run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(fs.existsSync(path.join(outputDir, 'images', 'help.png'))).toBe(true);
+        const html = fs.readFileSync(path.join(outputDir, 'tutorial.html'), 'utf-8');
+        expect(html).toContain('src="images/help.png"');
+    });
+
+    it('should apply base-url prefix to rewritten asset paths', () => {
+        fs.writeFileSync(path.join(inputDir, 'photo.png'), 'PNG_DATA');
+        fs.writeFileSync(
+            path.join(inputDir, 'Page.md'),
+            '---\npublic: true\nassets: true\n---\n# Page\n\n![Image](photo.png)\n',
+        );
+        run(['--input', inputDir, '--output', outputDir, '--base-url', '/my-repo']);
+        const html = fs.readFileSync(path.join(outputDir, 'page.html'), 'utf-8');
+        expect(html).toContain('src="/my-repo/photo.png"');
+    });
+
+    it('should warn for missing referenced assets', () => {
+        fs.writeFileSync(
+            path.join(inputDir, 'Page.md'),
+            '---\npublic: true\nassets: true\n---\n# Page\n\n![Missing](gone.png)\n',
+        );
+        const output = run(['--input', inputDir, '--output', outputDir]);
+        expect(output).toContain('warning');
+        expect(output).toContain('not found');
+    });
+});
+
+describe('nav.md custom navigation', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-nav-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        fs.mkdirSync(inputDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should use auto-generated nav when no nav.md exists', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\n');
+        fs.writeFileSync(path.join(inputDir, 'Beta.md'), '---\npublic: true\n---\n# Beta\n');
+        run(['--input', inputDir, '--output', outputDir]);
+        const html = fs.readFileSync(path.join(outputDir, 'alpha.html'), 'utf-8');
+        expect(html).toContain('site-nav');
+        expect(html).toContain('Alpha');
+        expect(html).toContain('Beta');
+        // Should have nav-current for auto-generated nav
+        expect(html).toContain('nav-current');
+    });
+
+    it('should render nav.md as custom navigation', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\n');
+        fs.writeFileSync(path.join(inputDir, 'Beta.md'), '---\npublic: true\n---\n# Beta\n');
+        fs.writeFileSync(
+            path.join(inputDir, 'nav.md'),
+            '- [[Alpha]]\n\n---\n\n- [[Beta]]\n',
+        );
+        const output = run(['--input', inputDir, '--output', outputDir]);
+        expect(output).toContain('nav.md');
+        const html = fs.readFileSync(path.join(outputDir, 'alpha.html'), 'utf-8');
+        expect(html).toContain('site-nav');
+        expect(html).toContain('alpha.html');
+        expect(html).toContain('beta.html');
+        // Should contain the <hr> from --- in nav.md
+        expect(html).toContain('<hr');
+    });
+
+    it('should not publish nav.md as a standalone page', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\n');
+        fs.writeFileSync(
+            path.join(inputDir, 'nav.md'),
+            '- [[Alpha]]\n',
+        );
+        run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        expect(fs.existsSync(path.join(outputDir, 'nav.html'))).toBe(false);
+    });
+
+    it('should apply base-url to wikilinks in nav.md', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\n');
+        fs.writeFileSync(
+            path.join(inputDir, 'nav.md'),
+            '- [[Alpha]]\n',
+        );
+        run(['--input', inputDir, '--output', outputDir, '--base-url', '/docs']);
+        const html = fs.readFileSync(path.join(outputDir, 'alpha.html'), 'utf-8');
+        expect(html).toContain('href="/docs/alpha.html"');
+    });
+
+    it('should apply base-url to wikilinks in article body', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\nSee [[Beta]] for more.\n');
+        fs.writeFileSync(path.join(inputDir, 'Beta.md'), '---\npublic: true\n---\n# Beta\nBack to [[Alpha]].\n');
+        run(['--input', inputDir, '--output', outputDir, '--base-url', '/docs']);
+        const alphaHtml = fs.readFileSync(path.join(outputDir, 'alpha.html'), 'utf-8');
+        const betaHtml = fs.readFileSync(path.join(outputDir, 'beta.html'), 'utf-8');
+        // Extract article body to avoid matching nav links
+        const alphaBody = alphaHtml.match(/<article[^>]*>([\s\S]*?)<\/article>/)?.[1] || '';
+        const betaBody = betaHtml.match(/<article[^>]*>([\s\S]*?)<\/article>/)?.[1] || '';
+        expect(alphaBody).toContain('href="/docs/beta.html"');
+        expect(betaBody).toContain('href="/docs/alpha.html"');
+    });
+
+    it('should support headings and markdown formatting in nav.md', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\n');
+        fs.writeFileSync(path.join(inputDir, 'Beta.md'), '---\npublic: true\n---\n# Beta\n');
+        fs.writeFileSync(
+            path.join(inputDir, 'nav.md'),
+            '### Section One\n\n- [[Alpha]]\n\n### Section Two\n\n- [[Beta]]\n',
+        );
+        run(['--input', inputDir, '--output', outputDir]);
+        const html = fs.readFileSync(path.join(outputDir, 'alpha.html'), 'utf-8');
+        expect(html).toContain('Section One');
+        expect(html).toContain('Section Two');
+        expect(html).toContain('<h3');
+    });
+
+    it('should not include nav.md in sitemap', () => {
+        fs.writeFileSync(path.join(inputDir, 'Alpha.md'), '---\npublic: true\n---\n# Alpha\n');
+        fs.writeFileSync(
+            path.join(inputDir, 'nav.md'),
+            '- [[Alpha]]\n',
+        );
+        run(['--input', inputDir, '--output', outputDir, '--default-public']);
+        const sitemap = fs.readFileSync(path.join(outputDir, 'sitemap.xml'), 'utf-8');
+        expect(sitemap).not.toContain('nav.html');
+        expect(sitemap).toContain('alpha.html');
+    });
+
+    it('should render nested wikilinks in bulleted list as inline links within a single li', () => {
+        fs.writeFileSync(path.join(inputDir, 'Plant.md'), '---\npublic: true\n---\n# Plant\n');
+        fs.writeFileSync(path.join(inputDir, 'Plant Foods.md'), '---\npublic: true\n---\n# Plant Foods\n');
+        fs.writeFileSync(path.join(inputDir, 'Demo.md'), '---\npublic: true\n---\n# Demo\n');
+        fs.writeFileSync(path.join(inputDir, 'Plant Based.md'), '---\npublic: true\n---\n# Plant Based\n');
+        fs.writeFileSync(
+            path.join(inputDir, 'nav.md'),
+            '- [[[[Plant]] Foods]]\n- [[Plant Based [[Demo]]]]\n',
+        );
+        run(['--input', inputDir, '--output', outputDir]);
+        const html = fs.readFileSync(path.join(outputDir, 'plant.html'), 'utf-8');
+        // Nested wikilinks should produce multiple <a> tags inside a single <li>
+        // [[[[Plant]] Foods]] -> <li>...<a>Plant</a><a> Foods</a>...</li>
+        const navMatch = html.match(/<nav class="site-nav">([\s\S]*?)<\/nav>/);
+        expect(navMatch).not.toBeNull();
+        const navHtml = navMatch![1];
+        // Each bulleted item should be a single <li> containing the wikilink parts
+        const liItems = navHtml.match(/<li>[\s\S]*?<\/li>/g) ?? [];
+        expect(liItems.length).toBe(2);
+        // First <li> should contain both "Plant" and "Foods" as links
+        expect(liItems[0]).toContain('plant.html');
+        expect(liItems[0]).toContain('plant-foods.html');
+        // Second <li> should contain both "Plant Based" and "Demo" as links
+        // Outer wikilink target is "Plant Based Demo" (inner brackets stripped) → plant-based-demo.html
+        expect(liItems[1]).toContain('demo.html');
+        expect(liItems[1]).toContain('plant-based-demo.html');
+    });
+});
+
+describe('--theme and --themes flags', () => {
+    let tmpDir: string;
+    let inputDir: string;
+    let outputDir: string;
+
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'as-notes-theme-test-'));
+        inputDir = path.join(tmpDir, 'notes');
+        outputDir = path.join(tmpDir, 'site');
+        fs.mkdirSync(inputDir, { recursive: true });
+        fs.writeFileSync(path.join(inputDir, 'Hello.md'), '---\npublic: true\n---\n# Hello\n');
+    });
+
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should not include sticky positioning in default theme nav', () => {
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--theme', 'default']);
+        const css = fs.readFileSync(path.join(outputDir, 'theme-default.css'), 'utf-8');
+        expect(css).not.toContain('position: sticky');
+        expect(css).not.toMatch(/[^-]height: 100vh/);
+        expect(css).not.toContain('overflow-y: auto');
+        expect(css).toContain('.site-nav');
+    });
+
+    it('should not include sticky positioning in dark theme nav', () => {
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--theme', 'dark']);
+        const css = fs.readFileSync(path.join(outputDir, 'theme-dark.css'), 'utf-8');
+        expect(css).not.toContain('position: sticky');
+        expect(css).not.toMatch(/[^-]height: 100vh/);
+        expect(css).not.toContain('overflow-y: auto');
+        expect(css).toContain('.site-nav');
+    });
+
+    it('should use custom theme from themes directory', () => {
+        const themesDir = path.join(tmpDir, 'themes');
+        fs.mkdirSync(themesDir, { recursive: true });
+        fs.writeFileSync(path.join(themesDir, 'default.css'), 'body { color: red; }');
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--theme', 'default', '--themes', themesDir]);
+        const css = fs.readFileSync(path.join(outputDir, 'theme-default.css'), 'utf-8');
+        expect(css).toBe('body { color: red; }');
+    });
+
+    it('should fall back to built-in theme when themes directory has no matching file', () => {
+        const themesDir = path.join(tmpDir, 'themes');
+        fs.mkdirSync(themesDir, { recursive: true });
+        // themesDir exists but has no default.css
+        run(['--input', inputDir, '--output', outputDir, '--default-public', '--theme', 'default', '--themes', themesDir]);
+        const css = fs.readFileSync(path.join(outputDir, 'theme-default.css'), 'utf-8');
+        expect(css).toContain('AS Notes default theme');
+    });
+
+    it('should load themes directory from config file', () => {
+        const themesDir = path.join(tmpDir, 'themes');
+        fs.mkdirSync(themesDir, { recursive: true });
+        fs.writeFileSync(path.join(themesDir, 'dark.css'), '.custom-dark { background: #000; }');
+        const configPath = path.join(tmpDir, 'asnotes-publish.json');
+        fs.writeFileSync(configPath, JSON.stringify({
+            inputDir: './notes',
+            outputDir: './site',
+            defaultPublic: true,
+            theme: 'dark',
+            themes: './themes',
+        }));
+        run(['--config', configPath]);
+        const css = fs.readFileSync(path.join(outputDir, 'theme-dark.css'), 'utf-8');
+        expect(css).toBe('.custom-dark { background: #000; }');
+    });
+
+    it('should log custom theme source', () => {
+        const themesDir = path.join(tmpDir, 'themes');
+        fs.mkdirSync(themesDir, { recursive: true });
+        fs.writeFileSync(path.join(themesDir, 'default.css'), 'body {}');
+        const output = run(['--input', inputDir, '--output', outputDir, '--default-public', '--theme', 'default', '--themes', themesDir]);
+        expect(output).toContain('(custom)');
+    });
+});
diff --git a/html-conversion/tsconfig.json b/publish/tsconfig.json
similarity index 100%
rename from html-conversion/tsconfig.json
rename to publish/tsconfig.json
diff --git a/html-conversion/vitest.config.ts b/publish/vitest.config.ts
similarity index 100%
rename from html-conversion/vitest.config.ts
rename to publish/vitest.config.ts
diff --git a/skills/as-notes-agent-use/SKILL.md b/skills/as-notes-agent-use/SKILL.md
index f2e4856..c0e7439 100644
--- a/skills/as-notes-agent-use/SKILL.md
+++ b/skills/as-notes-agent-use/SKILL.md
@@ -22,7 +22,7 @@ AS Notes turns VS Code into a PKMS. Activates when `.asnotes/` exists at the wor
 - Add `aliases:` front matter only when a page genuinely needs alternative names
 - Use task tags (`#P1`, `#D-YYYY-MM-DD`, etc.) inline on task lines - do not invent new tag formats
 - In outliner mode every line must start with `- `; use indentation for hierarchy
-- When the user's notes may be published as a static HTML site, ensure wikilinks and structure are clean - the `html-conversion` tool converts them to relative `.html` links
+- When the user's notes may be published as a static HTML site, ensure wikilinks and structure are clean - the `publish` tool converts them to relative `.html` links
 - See [Writing Notes in AS Notes Format](#writing-notes-in-as-notes-format) for templates
 
 ### When helping or troubleshooting (use case 2)
@@ -368,7 +368,7 @@ When a user reports a problem, work through these checks in order:
 
 ## Publishing to Static HTML
 
-`html-conversion` is a Node.js tool (`html-conversion/` in the repo) that converts a notes workspace to a static HTML site.
+`publish` is a Node.js tool (`publish/` in the repo) that converts a notes workspace to a static HTML site.
 
 - Scans `--input` for `.md` → outputs `.html` files
 - `[[wikilinks]]` → relative `.html` links; auto-generates `<nav>` sidebar
@@ -377,7 +377,7 @@ When a user reports a problem, work through these checks in order:
 - **Wipes output directory before each run**
 
 ```bash
-cd html-conversion && npm install && npm run build
+cd publish && npm install && npm run build
 npm run convert -- --input <notes-dir> --output <output-dir>
 ```
 
@@ -400,7 +400,7 @@ npm run convert -- \
 ```yaml
 - name: Build docs
   run: |
-    cd html-conversion && npm ci && npm run build
+    cd publish && npm ci && npm run build
     npm run convert -- --input ../docs-src/pages --output ../docs
 ```
 
diff --git a/vs-code-extension/build.mjs b/vs-code-extension/build.mjs
index c831783..5253607 100644
--- a/vs-code-extension/build.mjs
+++ b/vs-code-extension/build.mjs
@@ -118,6 +118,19 @@ const kanbanSidebarWebviewBuildOptions = {
     target: ['es2022'],
 };
 
+/** @type {import('esbuild').BuildOptions} */
+const convertBuildOptions = {
+    entryPoints: ['../publish/src/convert.ts'],
+    bundle: true,
+    outfile: 'dist/convert.js',
+    format: 'esm',
+    platform: 'node',
+    sourcemap: true,
+    banner: {
+        js: '#!/usr/bin/env node',
+    },
+};
+
 /** @type {import('esbuild').BuildOptions} */
 const calendarWebviewBuildOptions = {
     entryPoints: ['./src/webview/calendar.ts'],
@@ -193,12 +206,14 @@ if (isWatch) {
     const kanbanCtx = await esbuild.context(kanbanWebviewBuildOptions);
     const kanbanSidebarCtx = await esbuild.context(kanbanSidebarWebviewBuildOptions);
     const calendarCtx = await esbuild.context(calendarWebviewBuildOptions);
+    const convertCtx = await esbuild.context(convertBuildOptions);
     await extCtx.watch();
     await webCtx.watch();
     await searchCtx.watch();
     await kanbanCtx.watch();
     await kanbanSidebarCtx.watch();
     await calendarCtx.watch();
+    await convertCtx.watch();
     console.log('Watching for changes...');
 } else {
     await buildCss();
@@ -208,5 +223,6 @@ if (isWatch) {
     await esbuild.build(kanbanWebviewBuildOptions);
     await esbuild.build(kanbanSidebarWebviewBuildOptions);
     await esbuild.build(calendarWebviewBuildOptions);
+    await esbuild.build(convertBuildOptions);
     console.log('Build complete. WASM binary copied to dist/.');
 }
diff --git a/vs-code-extension/package.json b/vs-code-extension/package.json
index d2d91c9..8772755 100644
--- a/vs-code-extension/package.json
+++ b/vs-code-extension/package.json
@@ -2,7 +2,7 @@
     "name": "as-notes",
     "displayName": "AS Notes - Personal Knowledge Management System (PKMS)",
     "description": "VS Code Personal Knowledge Management System (PKMS) - Markdown Editing, Wikilinks (inc. Nested), Tasks, Kanban, Files, Publish to HTML, Daily Journal, Encrypted Notes",
-    "version": "2.2.7",
+    "version": "2.2.8",
     "publisher": "appsoftwareltd",
     "license": "Elastic-2.0",
     "icon": "images/icon.png",
@@ -35,7 +35,7 @@
         "theme": "dark"
     },
     "activationEvents": [
-        "onLanguage:markdown"
+        "*"
     ],
     "main": "./dist/extension.js",
     "contributes": {
@@ -173,6 +173,30 @@
             {
                 "command": "as-notes.insertTemplate",
                 "title": "AS Notes: Insert Template"
+            },
+            {
+                "command": "as-notes.togglePublic",
+                "title": "AS Notes: Toggle Public"
+            },
+            {
+                "command": "as-notes.cycleLayout",
+                "title": "AS Notes: Cycle Layout"
+            },
+            {
+                "command": "as-notes.toggleRetina",
+                "title": "AS Notes: Toggle Retina"
+            },
+            {
+                "command": "as-notes.toggleAssets",
+                "title": "AS Notes: Toggle Assets"
+            },
+            {
+                "command": "as-notes.publishToHtml",
+                "title": "AS Notes: Publish to HTML"
+            },
+            {
+                "command": "as-notes.configurePublish",
+                "title": "AS Notes: Configure Publish Settings"
             }
         ],
         "keybindings": [
diff --git a/vs-code-extension/src/FrontMatterService.ts b/vs-code-extension/src/FrontMatterService.ts
index 098e0fc..1a157a1 100644
--- a/vs-code-extension/src/FrontMatterService.ts
+++ b/vs-code-extension/src/FrontMatterService.ts
@@ -1,232 +1,4 @@
 /**
- * Lightweight YAML front matter parser for extracting metadata from markdown files.
- *
- * Supports the standard YAML front matter format delimited by `---` fences at
- * the start of the file. Currently extracts the `aliases` field, with the
- * flexibility to add more fields (e.g. `tags`) in the future.
- *
- * Supports two alias formats:
- *
- * List style:
- * ```yaml
- * ---
- * aliases:
- *   - Alias One
- *   - Alias Two
- * ---
- * ```
- *
- * Inline array style:
- * ```yaml
- * ---
- * aliases: [Alias One, Alias Two]
- * ---
- * ```
- *
- * Alias values are plain strings — any accidental `[[` or `]]` bracket syntax
- * is stripped automatically.
+ * Re-export from common package. FrontMatterService has been moved to as-notes-common.
  */
-export class FrontMatterService {
-
-    /**
-     * Extract the raw front matter block from markdown content.
-     * Returns the text between the first two `---` lines, or null if
-     * no valid front matter block is found.
-     *
-     * Front matter must start at the very beginning of the file (line 0).
-     */
-    extractFrontMatter(content: string): string | null {
-        const lines = content.split(/\r?\n/);
-        if (lines.length === 0 || lines[0].trim() !== '---') {
-            return null;
-        }
-
-        // Find the closing ---
-        for (let i = 1; i < lines.length; i++) {
-            if (lines[i].trim() === '---') {
-                // Return the block between the fences (exclusive of the --- lines)
-                return lines.slice(1, i).join('\n');
-            }
-        }
-
-        return null; // No closing fence found
-    }
-
-    /**
-     * Parse aliases from markdown file content.
-     *
-     * Extracts the `aliases:` field from the YAML front matter and returns
-     * an array of alias name strings. Returns an empty array if no front
-     * matter exists or no aliases are defined.
-     *
-     * Strips any accidental `[[` / `]]` wikilink brackets from alias values.
-     */
-    parseAliases(content: string): string[] {
-        const frontMatter = this.extractFrontMatter(content);
-        if (!frontMatter) {
-            return [];
-        }
-
-        return this.parseAliasesFromFrontMatter(frontMatter);
-    }
-
-    /**
-     * Parse the aliases field from a front matter block (without the --- fences).
-     */
-    private parseAliasesFromFrontMatter(frontMatter: string): string[] {
-        const lines = frontMatter.split(/\r?\n/);
-
-        // Find the aliases: line
-        let aliasLineIndex = -1;
-        let aliasLineContent = '';
-        for (let i = 0; i < lines.length; i++) {
-            const match = lines[i].match(/^aliases\s*:\s*(.*)/);
-            if (match) {
-                aliasLineIndex = i;
-                aliasLineContent = match[1].trim();
-                break;
-            }
-        }
-
-        if (aliasLineIndex === -1) {
-            return [];
-        }
-
-        // Check for inline array: aliases: [Alias One, Alias Two]
-        if (aliasLineContent.startsWith('[')) {
-            return this.parseInlineArray(aliasLineContent);
-        }
-
-        // Check for a single inline value: aliases: Some Alias
-        if (aliasLineContent.length > 0) {
-            const cleaned = this.cleanAliasValue(aliasLineContent);
-            return cleaned ? [cleaned] : [];
-        }
-
-        // List style: collect subsequent indented `- item` lines
-        return this.parseListItems(lines, aliasLineIndex + 1);
-    }
-
-    /**
-     * Parse an inline array like `[Alias One, Alias Two]`.
-     */
-    private parseInlineArray(value: string): string[] {
-        // Remove surrounding brackets
-        const inner = value.replace(/^\[/, '').replace(/\]$/, '');
-        if (inner.trim().length === 0) {
-            return [];
-        }
-
-        return inner
-            .split(',')
-            .map(item => this.cleanAliasValue(item.trim()))
-            .filter((item): item is string => item !== null && item.length > 0);
-    }
-
-    /**
-     * Parse list-style items starting from the given line index.
-     * Collects lines matching `  - value` until a non-list line is hit.
-     */
-    private parseListItems(lines: string[], startIndex: number): string[] {
-        const aliases: string[] = [];
-
-        for (let i = startIndex; i < lines.length; i++) {
-            const match = lines[i].match(/^\s+-\s+(.*)/);
-            if (!match) {
-                break; // End of list
-            }
-            const cleaned = this.cleanAliasValue(match[1].trim());
-            if (cleaned && cleaned.length > 0) {
-                aliases.push(cleaned);
-            }
-        }
-
-        return aliases;
-    }
-
-    /**
-     * Clean an alias value by stripping accidental wikilink brackets and
-     * surrounding quotes.
-     *
-     * @returns The cleaned string, or null if the result is empty.
-     */
-    private cleanAliasValue(value: string): string | null {
-        // Strip surrounding quotes (single or double)
-        let cleaned = value.replace(/^["']|["']$/g, '');
-        // Strip any [[ or ]] bracket syntax
-        cleaned = cleaned.replace(/\[\[|\]\]/g, '');
-        cleaned = cleaned.trim();
-        return cleaned.length > 0 ? cleaned : null;
-    }
-
-    /**
-     * Update a specific alias in the front matter of a markdown file.
-     * Returns the modified file content, or null if the alias was not found.
-     *
-     * Handles both list-style and inline array formats.
-     */
-    updateAlias(content: string, oldAlias: string, newAlias: string): string | null {
-        const lines = content.split(/\r?\n/);
-        if (lines.length === 0 || lines[0].trim() !== '---') {
-            return null;
-        }
-
-        // Find closing fence
-        let closingIndex = -1;
-        for (let i = 1; i < lines.length; i++) {
-            if (lines[i].trim() === '---') {
-                closingIndex = i;
-                break;
-            }
-        }
-        if (closingIndex === -1) {
-            return null;
-        }
-
-        // Find the aliases: line within the front matter
-        let aliasLineIndex = -1;
-        for (let i = 1; i < closingIndex; i++) {
-            if (lines[i].match(/^aliases\s*:/)) {
-                aliasLineIndex = i;
-                break;
-            }
-        }
-        if (aliasLineIndex === -1) {
-            return null;
-        }
-
-        const aliasLine = lines[aliasLineIndex];
-        const afterColon = aliasLine.replace(/^aliases\s*:\s*/, '').trim();
-
-        // Inline array format: aliases: [Alias One, Alias Two]
-        if (afterColon.startsWith('[')) {
-            const updated = aliasLine.replace(oldAlias, newAlias);
-            if (updated === aliasLine) {
-                return null; // oldAlias not found
-            }
-            lines[aliasLineIndex] = updated;
-            return lines.join('\n');
-        }
-
-        // Single inline value: aliases: Some Alias
-        if (afterColon.length > 0 && this.cleanAliasValue(afterColon) === oldAlias) {
-            lines[aliasLineIndex] = aliasLine.replace(oldAlias, newAlias);
-            return lines.join('\n');
-        }
-
-        // List style: find the matching `- oldAlias` line
-        for (let i = aliasLineIndex + 1; i < closingIndex; i++) {
-            const match = lines[i].match(/^(\s+-\s+)(.*)/);
-            if (!match) {
-                break;
-            }
-            const cleaned = this.cleanAliasValue(match[2].trim());
-            if (cleaned === oldAlias) {
-                lines[i] = match[1] + newAlias;
-                return lines.join('\n');
-            }
-        }
-
-        return null; // alias not found
-    }
-}
+export { FrontMatterService, type FrontMatterFields } from 'as-notes-common';
diff --git a/vs-code-extension/src/IndexService.ts b/vs-code-extension/src/IndexService.ts
index 8a9bfb6..f0f6803 100644
--- a/vs-code-extension/src/IndexService.ts
+++ b/vs-code-extension/src/IndexService.ts
@@ -2,7 +2,7 @@ import initSqlJs, { type Database } from 'sql.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import { WikilinkService, Wikilink } from 'as-notes-common';
-import { FrontMatterService } from './FrontMatterService.js';
+import { FrontMatterService } from 'as-notes-common';
 import { LogService, NO_OP_LOGGER } from './LogService.js';
 
 // ── Row types ──────────────────────────────────────────────────────────────
diff --git a/vs-code-extension/src/PublishService.ts b/vs-code-extension/src/PublishService.ts
new file mode 100644
index 0000000..e09b284
--- /dev/null
+++ b/vs-code-extension/src/PublishService.ts
@@ -0,0 +1,1338 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import * as vscode from 'vscode';
+import { FrontMatterService } from 'as-notes-common';
+
+const frontMatterService = new FrontMatterService();
+
+const CONFIG_FILENAME = 'asnotes-publish.json';
+
+interface PublishConfig {
+    inputDir?: string;
+    defaultPublic?: boolean;
+    defaultAssets?: boolean;
+    layout?: string;
+    layouts?: string;
+    includes?: string;
+    theme?: string;
+    themes?: string;
+    baseUrl?: string;
+    retina?: boolean;
+    includeDrafts?: boolean;
+    stylesheets?: string[];
+    exclude?: string[];
+    outputDir?: string;
+}
+
+/**
+ * Toggle or set a front matter field in the current document.
+ * Creates a front matter block if one does not exist.
+ */
+export async function toggleFrontMatterField(
+    editor: vscode.TextEditor,
+    field: string,
+    value: string | boolean,
+): Promise<void> {
+    const document = editor.document;
+    const content = document.getText();
+    const lines = content.split(/\r?\n/);
+
+    const hasFrontMatter = lines.length > 0 && lines[0].trim() === '---';
+
+    await editor.edit(editBuilder => {
+        if (!hasFrontMatter) {
+            // Insert new front matter at the top
+            const yaml = `---\n${field}: ${formatYamlValue(value)}\n---\n`;
+            editBuilder.insert(new vscode.Position(0, 0), yaml);
+            return;
+        }
+
+        // Find closing ---
+        let closingIndex = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === '---') {
+                closingIndex = i;
+                break;
+            }
+        }
+
+        if (closingIndex === -1) {
+            // Malformed front matter - insert at line 1
+            const lineEnd = new vscode.Position(0, lines[0].length);
+            editBuilder.insert(lineEnd, `\n${field}: ${formatYamlValue(value)}`);
+            return;
+        }
+
+        // Check if field already exists
+        const fieldRegex = new RegExp(`^${escapeRegExp(field)}\\s*:`, 'i');
+        let fieldLine = -1;
+        for (let i = 1; i < closingIndex; i++) {
+            if (fieldRegex.test(lines[i])) {
+                fieldLine = i;
+                break;
+            }
+        }
+
+        if (fieldLine !== -1) {
+            // Field exists - toggle or update
+            const currentLine = lines[fieldLine];
+            if (typeof value === 'boolean') {
+                // Toggle boolean
+                const currentValue = /:\s*true\s*$/i.test(currentLine);
+                const newLine = `${field}: ${!currentValue}`;
+                const range = new vscode.Range(fieldLine, 0, fieldLine, currentLine.length);
+                editBuilder.replace(range, newLine);
+            } else {
+                // Update string value
+                const newLine = `${field}: ${formatYamlValue(value)}`;
+                const range = new vscode.Range(fieldLine, 0, fieldLine, currentLine.length);
+                editBuilder.replace(range, newLine);
+            }
+        } else {
+            // Field doesn't exist - insert before closing ---
+            const insertPos = new vscode.Position(closingIndex, 0);
+            editBuilder.insert(insertPos, `${field}: ${formatYamlValue(value)}\n`);
+        }
+    });
+}
+
+/**
+ * Cycle a front matter field through a set of values.
+ * If the current value is the last in the list, wraps to the first.
+ */
+export async function cycleFrontMatterField(
+    editor: vscode.TextEditor,
+    field: string,
+    values: string[],
+): Promise<void> {
+    const content = editor.document.getText();
+    const fields = frontMatterService.parseFrontMatterFields(content);
+    const currentValue = (fields as Record<string, unknown>)[field] as string | undefined;
+    const currentIndex = currentValue ? values.indexOf(currentValue) : -1;
+    const nextIndex = (currentIndex + 1) % values.length;
+    await toggleFrontMatterField(editor, field, values[nextIndex]);
+}
+
+function formatYamlValue(value: string | boolean): string {
+    if (typeof value === 'boolean') return value.toString();
+    // Quote strings that contain special YAML characters
+    if (/[:#{}[\],&*?|>!%@`]/.test(value) || value.includes("'") || value.includes('"')) {
+        return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    return value;
+}
+
+function escapeRegExp(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Read the publish config file from the notes root.
+ * Returns undefined if the file does not exist.
+ */
+function readPublishConfig(notesRoot: string): PublishConfig | undefined {
+    const configPath = path.join(notesRoot, CONFIG_FILENAME);
+    if (!fs.existsSync(configPath)) return undefined;
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed as PublishConfig;
+        }
+    } catch {
+        // Corrupt config - treat as missing
+    }
+    return undefined;
+}
+
+/**
+ * Ensure all config fields are present with sensible defaults.
+ * This lets users discover available options by reading the config file.
+ */
+function withDefaults(config: PublishConfig): Required<PublishConfig> {
+    return {
+        inputDir: config.inputDir ?? '',
+        defaultPublic: config.defaultPublic ?? false,
+        defaultAssets: config.defaultAssets ?? false,
+        layout: config.layout ?? 'docs',
+        layouts: config.layouts ?? '',
+        includes: config.includes ?? '',
+        theme: config.theme ?? 'default',
+        themes: config.themes ?? '',
+        baseUrl: config.baseUrl ?? '',
+        retina: config.retina ?? false,
+        includeDrafts: config.includeDrafts ?? false,
+        stylesheets: config.stylesheets ?? [],
+        exclude: config.exclude ?? [],
+        outputDir: config.outputDir ?? '',
+    };
+}
+
+/**
+ * Write the publish config to the notes root.
+ * All fields are included with defaults so users can discover available options.
+ */
+function writePublishConfig(notesRoot: string, config: PublishConfig, configFilename?: string): void {
+    const filename = configFilename ?? CONFIG_FILENAME;
+    const configPath = path.join(notesRoot, filename);
+    fs.writeFileSync(configPath, JSON.stringify(withDefaults(config), null, 4) + '\n', 'utf-8');
+}
+
+/**
+ * Discover all publish config files in the notes root.
+ * Returns an array of { filename, config } sorted by filename.
+ */
+function discoverConfigFiles(notesRoot: string): { filename: string; config: PublishConfig }[] {
+    const results: { filename: string; config: PublishConfig }[] = [];
+    try {
+        const files = fs.readdirSync(notesRoot);
+        for (const file of files) {
+            if (/^asnotes-publish(\.[^.]+)?\.json$/i.test(file)) {
+                try {
+                    const raw = fs.readFileSync(path.join(notesRoot, file), 'utf-8');
+                    const parsed = JSON.parse(raw);
+                    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                        results.push({ filename: file, config: parsed as PublishConfig });
+                    }
+                } catch {
+                    // Skip corrupt configs
+                }
+            }
+        }
+    } catch {
+        // Directory not readable
+    }
+    return results.sort((a, b) => a.filename.localeCompare(b.filename));
+}
+
+/**
+ * Derive the config filename from the input directory.
+ * Notes root -> asnotes-publish.json
+ * Subdirectory -> asnotes-publish.<dirname>.json
+ */
+function configFilenameForInputDir(notesRoot: string, inputDir: string): string {
+    if (!inputDir) return CONFIG_FILENAME;
+    const resolved = path.isAbsolute(inputDir) ? inputDir : path.resolve(notesRoot, inputDir);
+    const resolvedRoot = path.resolve(notesRoot);
+    if (resolved === resolvedRoot) return CONFIG_FILENAME;
+    const dirName = path.basename(resolved);
+    return `asnotes-publish.${dirName}.json`;
+}
+
+/**
+ * Convert a chosen filesystem path to a relative path if inside the workspace, otherwise keep absolute.
+ */
+function toRelativePath(notesRoot: string, chosenPath: string): string {
+    const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+    if (workspaceRoot && chosenPath.startsWith(workspaceRoot)) {
+        const rel = path.relative(notesRoot, chosenPath);
+        return rel.startsWith('..') ? chosenPath : './' + rel.replace(/\\/g, '/');
+    }
+    return chosenPath;
+}
+
+const DEFAULT_HEADER_HTML = `<div class="site-header">
+    <a class="site-title" href="{{base-url}}/">
+        <svg class="site-logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 191.82 166.13" width="24" height="21"><path fill="currentColor" fill-rule="evenodd" d="M67.09,132.92,47.93,166.13H9.59L0,149.52,86.33,0H105.5L19.17,149.52H38.34l19.17-33.2h76.8l9.59,16.6Zm48-83.12,9.65,16.71H143.9L115.08,16.6q-24,41.57-48,83.12H143.9q14.37,24.9,28.76,49.8h-96l-9.59,16.61H182.24l9.58-16.61-38.34-66.4H96C95.85,82.9,113.39,52.73,115.08,49.8Z"/></svg>
+    </a>
+</div>
+`;
+
+const DEFAULT_FOOTER_HTML = `<div class="site-footer">
+    <p>&copy; ${new Date().getFullYear()} Built with <a href="https://www.asnotes.io">AS Notes</a> by <a href="https://www.appsoftware.com">App Software Ltd</a></p>
+</div>
+`;
+
+/**
+ * Create default header.html and footer.html in the includes directory if they do not already exist.
+ */
+async function createDefaultPartials(includesDirPath: string): Promise<void> {
+    if (!fs.existsSync(includesDirPath)) {
+        fs.mkdirSync(includesDirPath, { recursive: true });
+    }
+
+    const headerPath = path.join(includesDirPath, 'header.html');
+    if (!fs.existsSync(headerPath)) {
+        fs.writeFileSync(headerPath, DEFAULT_HEADER_HTML, 'utf-8');
+    }
+
+    const footerPath = path.join(includesDirPath, 'footer.html');
+    if (!fs.existsSync(footerPath)) {
+        fs.writeFileSync(footerPath, DEFAULT_FOOTER_HTML, 'utf-8');
+    }
+}
+
+const LAYOUT_DOCS = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="docs">
+{{header}}{{nav}}
+    <article class="markdown-body">
+{{toc}}
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
+`;
+
+const LAYOUT_BLOG = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="blog">
+{{header}}    <article class="blog-post">
+{{date}}{{toc}}
+{{content}}
+    </article>
+{{nav}}{{footer}}</body>
+</html>
+`;
+
+const LAYOUT_MINIMAL = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{title}}</title>{{stylesheets}}{{meta}}
+</head>
+<body data-layout="minimal">
+{{header}}    <article>
+{{content}}
+    </article>
+{{footer}}</body>
+</html>
+`;
+
+const LAYOUT_TEMPLATES: Record<string, string> = {
+    docs: LAYOUT_DOCS,
+    blog: LAYOUT_BLOG,
+    minimal: LAYOUT_MINIMAL,
+};
+
+/**
+ * Create default layout template files in the layouts directory if they do not already exist.
+ */
+async function createDefaultLayouts(layoutsDirPath: string): Promise<void> {
+    if (!fs.existsSync(layoutsDirPath)) {
+        fs.mkdirSync(layoutsDirPath, { recursive: true });
+    }
+
+    for (const [name, template] of Object.entries(LAYOUT_TEMPLATES)) {
+        const layoutPath = path.join(layoutsDirPath, `${name}.html`);
+        if (!fs.existsSync(layoutPath)) {
+            fs.writeFileSync(layoutPath, template, 'utf-8');
+        }
+    }
+}
+
+const THEME_DEFAULT = `/* AS Notes default theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #24292e;
+    background: #ffffff;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #f6f8fa;
+    border-bottom: 1px solid #d0d7de;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #24292e;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #0366d6;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #d0d7de;
+    background: #f6f8fa;
+    font-size: 0.85rem;
+    color: #586069;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #0366d6;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #f6f8fa;
+    border-right: 1px solid #d0d7de;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #24292f;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #eaeef2;
+}
+
+.site-nav ul li:hover a {
+    color: #0550ae;
+}
+
+.site-nav ul li.nav-current {
+    background: #ddf4ff;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #0550ae;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+}
+
+a {
+    color: #0366d6;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #f6f8fa;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #f6f8fa;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #f6f8fa;
+    border: 1px solid #e1e4e8;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #586069;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #cb2431;
+    font-style: italic;
+}
+
+/* -- Blog layout (single column, nav below content) --------------- */
+
+body[data-layout="blog"] {
+    display: block;
+}
+
+body[data-layout="blog"] article.blog-post {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 3rem;
+}
+
+body[data-layout="blog"] .site-nav {
+    border-right: none;
+    border-top: 1px solid #d0d7de;
+    padding: 1.5rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+body[data-layout="blog"] .site-nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #d0d7de;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
+`;
+
+const THEME_DARK = `/* AS Notes dark theme */
+
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    margin: 0;
+    padding: 0;
+}
+
+/* -- Layout grid -------------------------------------------------- */
+
+body {
+    display: grid;
+    grid-template-columns: 220px 1fr;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100vh;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #c9d1d9;
+    background: #0d1117;
+}
+
+/* -- Header / footer ---------------------------------------------- */
+
+header {
+    grid-column: 1 / -1;
+    grid-row: 1;
+}
+
+footer {
+    grid-column: 1 / -1;
+    grid-row: 3;
+}
+
+.site-header {
+    display: flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: #161b22;
+    border-bottom: 1px solid #30363d;
+}
+
+.site-header .site-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    font-size: 1rem;
+    color: #c9d1d9;
+    text-decoration: none;
+}
+
+.site-header .site-title:hover {
+    color: #58a6ff;
+}
+
+.site-header .site-logo {
+    flex-shrink: 0;
+}
+
+.site-footer {
+    padding: 1rem 1.5rem;
+    border-top: 1px solid #30363d;
+    background: #161b22;
+    font-size: 0.85rem;
+    color: #8b949e;
+    text-align: center;
+}
+
+.site-footer a {
+    color: #58a6ff;
+}
+
+/* -- Sidebar nav -------------------------------------------------- */
+
+.site-nav {
+    grid-column: 1;
+    grid-row: 2;
+    background: #161b22;
+    border-right: 1px solid #30363d;
+    padding: 1.5rem 1rem;
+}
+
+.site-nav ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.site-nav ul li {
+    margin: 0.2rem 0;
+    padding: 0.3rem 0.6rem;
+    border-radius: 6px;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    cursor: pointer;
+}
+
+.site-nav ul li a {
+    text-decoration: none;
+    color: #c9d1d9;
+}
+
+.site-nav ul li a:hover {
+    text-decoration: underline;
+}
+
+.site-nav ul li:hover {
+    background: #1f2937;
+}
+
+.site-nav ul li:hover a {
+    color: #58a6ff;
+}
+
+.site-nav ul li.nav-current {
+    background: #1f2937;
+    font-weight: 600;
+}
+
+.site-nav ul li.nav-current a {
+    color: #58a6ff;
+}
+
+/* -- Content ------------------------------------------------------ */
+
+article {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.markdown-body {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 900px;
+    overflow-x: auto;
+}
+
+article.blog-post {
+    grid-column: 2;
+    grid-row: 2;
+    padding: 2rem 3rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+/* -- Typography --------------------------------------------------- */
+
+h1, h2, h3, h4 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+    color: #f0f6fc;
+}
+
+a {
+    color: #58a6ff;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+/* -- Code --------------------------------------------------------- */
+
+code {
+    background: #161b22;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 85%;
+}
+
+pre {
+    background: #161b22;
+    padding: 16px;
+    border-radius: 6px;
+    overflow-x: auto;
+}
+
+pre code {
+    background: none;
+    padding: 0;
+}
+
+/* -- Images ------------------------------------------------------- */
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+/* -- Table of contents -------------------------------------------- */
+
+.toc {
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    padding: 12px 20px;
+    margin-bottom: 24px;
+}
+
+.toc summary {
+    font-weight: 600;
+    cursor: pointer;
+    color: #f0f6fc;
+}
+
+.toc ul {
+    margin: 8px 0 0 0;
+}
+
+.toc li {
+    margin: 4px 0;
+}
+
+/* -- Blog date ---------------------------------------------------- */
+
+.page-date {
+    display: block;
+    color: #8b949e;
+    font-size: 0.9em;
+    margin-bottom: 16px;
+}
+
+/* -- Missing page ------------------------------------------------- */
+
+.missing-page {
+    color: #f85149;
+    font-style: italic;
+}
+
+/* -- Blog layout (single column, nav below content) --------------- */
+
+body[data-layout="blog"] {
+    display: block;
+}
+
+body[data-layout="blog"] article.blog-post {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 3rem;
+}
+
+body[data-layout="blog"] .site-nav {
+    border-right: none;
+    border-top: 1px solid #30363d;
+    padding: 1.5rem;
+    max-width: 720px;
+    margin: 0 auto;
+}
+
+body[data-layout="blog"] .site-nav ul {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+/* -- Responsive --------------------------------------------------- */
+
+@media (max-width: 700px) {
+    body {
+        grid-template-columns: 1fr;
+    }
+
+    .site-nav {
+        border-right: none;
+        border-bottom: 1px solid #30363d;
+    }
+
+    article,
+    article.markdown-body,
+    article.blog-post {
+        padding: 1.5rem;
+    }
+}
+`;
+
+const THEME_TEMPLATES: Record<string, string> = {
+    default: THEME_DEFAULT,
+    dark: THEME_DARK,
+};
+
+/**
+ * Create default theme CSS files in the themes directory if they do not already exist.
+ */
+async function createDefaultThemes(themesDirPath: string): Promise<void> {
+    if (!fs.existsSync(themesDirPath)) {
+        fs.mkdirSync(themesDirPath, { recursive: true });
+    }
+
+    for (const [name, css] of Object.entries(THEME_TEMPLATES)) {
+        const themePath = path.join(themesDirPath, `${name}.css`);
+        if (!fs.existsSync(themePath)) {
+            fs.writeFileSync(themePath, css, 'utf-8');
+        }
+    }
+}
+
+/**
+ * Interactive wizard to configure publish settings.
+ * Returns undefined if the user cancels at any step.
+ */
+async function runPublishWizard(notesRoot: string, existing?: PublishConfig): Promise<PublishConfig | undefined> {
+    const config: PublishConfig = { ...existing };
+
+    // Step 1: Input Directory
+    const inputDirPick = await vscode.window.showQuickPick(
+        [
+            { label: '$(root-folder) Notes root', description: `Use ${notesRoot} as the input directory`, value: 'root' },
+            { label: '$(folder-opened) Choose a subdirectory...', description: 'Pick a specific folder to publish', value: 'pick' },
+        ],
+        { placeHolder: 'Input directory', title: 'Publish Settings (1/10)' },
+    );
+    if (!inputDirPick) return undefined;
+
+    if (inputDirPick.value === 'pick') {
+        const chosen = await vscode.window.showOpenDialog({
+            canSelectFiles: false,
+            canSelectFolders: true,
+            canSelectMany: false,
+            defaultUri: vscode.Uri.file(notesRoot),
+            openLabel: 'Select Input Directory',
+            title: 'Publish Settings (1/10): Input Directory',
+        });
+        if (!chosen || chosen.length === 0) return undefined;
+        config.inputDir = toRelativePath(notesRoot, chosen[0].fsPath);
+    } else {
+        config.inputDir = '';
+    }
+
+    // Step 2: Output Directory
+    const outputDir = await pickOutputDirectory(notesRoot, config.inputDir, config.outputDir);
+    if (!outputDir) return undefined;
+    config.outputDir = outputDir;
+
+    // Step 3: Base URL
+    const baseUrlInput = await vscode.window.showInputBox({
+        prompt: 'URL path prefix for deployed site (leave empty for root)',
+        title: 'Publish Settings (3/10)',
+        value: config.baseUrl ?? '',
+        placeHolder: '/my-repo',
+    });
+    if (baseUrlInput === undefined) return undefined;
+    config.baseUrl = baseUrlInput.replace(/\/+$/, '');
+
+    // Step 4: Default Public
+    const publicPick = await vscode.window.showQuickPick(
+        [
+            { label: 'Yes', description: 'All pages are published unless public: false', value: true },
+            { label: 'No', description: 'Only pages with public: true are published', value: false },
+        ],
+        { placeHolder: 'Publish all pages by default?', title: 'Publish Settings (4/10)' },
+    );
+    if (!publicPick) return undefined;
+    config.defaultPublic = publicPick.value;
+
+    // Step 5: Default Assets
+    const assetsPick = await vscode.window.showQuickPick(
+        [
+            { label: 'Yes', description: 'Copy referenced images and files', value: true },
+            { label: 'No', description: 'Only copy assets for pages with assets: true', value: false },
+        ],
+        { placeHolder: 'Copy referenced assets by default?', title: 'Publish Settings (5/10)' },
+    );
+    if (!assetsPick) return undefined;
+    config.defaultAssets = assetsPick.value;
+
+    // Step 6: Layout
+    const layoutPick = await vscode.window.showQuickPick(
+        [
+            { label: 'docs', description: 'Navigation sidebar + content area (default)' },
+            { label: 'blog', description: 'Navigation + blog-style article with date' },
+            { label: 'minimal', description: 'Content only, no navigation' },
+        ],
+        { placeHolder: 'Choose a layout', title: 'Publish Settings (6/10)' },
+    );
+    if (!layoutPick) return undefined;
+    config.layout = layoutPick.label;
+
+    // Step 7: Theme
+    const themePick = await vscode.window.showQuickPick(
+        [
+            { label: 'default', description: 'Light theme with GitHub-inspired typography' },
+            { label: 'dark', description: 'Dark theme' },
+            { label: 'none', description: 'No built-in theme (use custom stylesheets)' },
+        ],
+        { placeHolder: 'Choose a theme', title: 'Publish Settings (7/10)' },
+    );
+    if (!themePick) return undefined;
+    config.theme = themePick.label === 'none' ? '' : themePick.label;
+
+    // Step 8: Themes Directory
+    const themesDirPick = await vscode.window.showQuickPick(
+        [
+            { label: '$(new-folder) Create default themes', description: 'Create a themes directory with editable theme CSS files (default, dark)', value: 'create' },
+            { label: '$(folder-opened) Browse...', description: 'Choose an existing themes directory', value: 'pick' },
+            { label: 'Skip', description: 'Use built-in themes only', value: 'skip' },
+        ],
+        { placeHolder: 'Themes directory?', title: 'Publish Settings (8/10)' },
+    );
+    if (!themesDirPick) return undefined;
+
+    if (themesDirPick.value === 'create') {
+        const inputDirName = config.inputDir ? path.basename(path.resolve(notesRoot, config.inputDir)) : '';
+        const themesFolderName = inputDirName ? `asnotes-publish.themes.${inputDirName}` : 'asnotes-publish.themes';
+        const defaultThemesPath = path.join(notesRoot, themesFolderName);
+        await createDefaultThemes(defaultThemesPath);
+        config.themes = './' + themesFolderName;
+    } else if (themesDirPick.value === 'pick') {
+        const chosen = await vscode.window.showOpenDialog({
+            canSelectFiles: false,
+            canSelectFolders: true,
+            canSelectMany: false,
+            defaultUri: vscode.Uri.file(notesRoot),
+            openLabel: 'Select Themes Directory',
+            title: 'Publish Settings (8/10): Themes Directory',
+        });
+        if (chosen && chosen.length > 0) {
+            config.themes = toRelativePath(notesRoot, chosen[0].fsPath);
+        }
+    }
+
+    // Step 9: Layouts Directory
+    const layoutsDirPick = await vscode.window.showQuickPick(
+        [
+            { label: '$(new-folder) Create default layouts', description: 'Create a layouts directory with editable layout templates (docs, blog, minimal)', value: 'create' },
+            { label: '$(folder-opened) Browse...', description: 'Choose an existing layouts directory', value: 'pick' },
+            { label: 'Skip', description: 'Use built-in layouts only', value: 'skip' },
+        ],
+        { placeHolder: 'Layouts directory?', title: 'Publish Settings (9/10)' },
+    );
+    if (!layoutsDirPick) return undefined;
+
+    if (layoutsDirPick.value === 'create') {
+        const inputDirName = config.inputDir ? path.basename(path.resolve(notesRoot, config.inputDir)) : '';
+        const layoutsFolderName = inputDirName ? `asnotes-publish.layouts.${inputDirName}` : 'asnotes-publish.layouts';
+        const defaultLayoutsPath = path.join(notesRoot, layoutsFolderName);
+        await createDefaultLayouts(defaultLayoutsPath);
+        config.layouts = './' + layoutsFolderName;
+    } else if (layoutsDirPick.value === 'pick') {
+        const chosen = await vscode.window.showOpenDialog({
+            canSelectFiles: false,
+            canSelectFolders: true,
+            canSelectMany: false,
+            defaultUri: vscode.Uri.file(notesRoot),
+            openLabel: 'Select Layouts Directory',
+            title: 'Publish Settings (9/10): Layouts Directory',
+        });
+        if (chosen && chosen.length > 0) {
+            config.layouts = toRelativePath(notesRoot, chosen[0].fsPath);
+        }
+    }
+
+    // Step 10: Includes Directory
+    const includesDirPick = await vscode.window.showQuickPick(
+        [
+            { label: '$(new-folder) Create default includes', description: 'Create an includes directory with default header and footer templates', value: 'create' },
+            { label: '$(folder-opened) Browse...', description: 'Choose an existing includes directory', value: 'pick' },
+            { label: 'Skip', description: 'Use built-in header and footer only', value: 'skip' },
+        ],
+        { placeHolder: 'Includes directory?', title: 'Publish Settings (10/10)' },
+    );
+    if (!includesDirPick) return undefined;
+
+    if (includesDirPick.value === 'create') {
+        const inputDirName = config.inputDir ? path.basename(path.resolve(notesRoot, config.inputDir)) : '';
+        const includesFolderName = inputDirName ? `asnotes-publish.includes.${inputDirName}` : 'asnotes-publish.includes';
+        const defaultIncludesPath = path.join(notesRoot, includesFolderName);
+        await createDefaultPartials(defaultIncludesPath);
+        config.includes = './' + includesFolderName;
+    } else if (includesDirPick.value === 'pick') {
+        const chosen = await vscode.window.showOpenDialog({
+            canSelectFiles: false,
+            canSelectFolders: true,
+            canSelectMany: false,
+            defaultUri: vscode.Uri.file(notesRoot),
+            openLabel: 'Select Includes Directory',
+            title: 'Publish Settings (10/10): Includes Directory',
+        });
+        if (chosen && chosen.length > 0) {
+            config.includes = toRelativePath(notesRoot, chosen[0].fsPath);
+        }
+    }
+
+    return config;
+}
+
+/**
+ * Pick an output directory. Shows a QuickPick with a sensible default and browse option.
+ * Returns the chosen path (relative to notesRoot if inside it, otherwise absolute), or undefined if cancelled.
+ */
+async function pickOutputDirectory(notesRoot: string, inputDir?: string, savedDir?: string): Promise<string | undefined> {
+    // Derive a sensible default: <inputDirName>-publish, or just "publish"
+    const inputDirName = inputDir ? path.basename(path.resolve(notesRoot, inputDir)) : '';
+    const defaultDirName = inputDirName ? `./${inputDirName}-publish` : './publish';
+
+    if (savedDir) {
+        const resolvedSaved = path.isAbsolute(savedDir) ? savedDir : path.resolve(notesRoot, savedDir);
+        const pick = await vscode.window.showQuickPick(
+            [
+                { label: `$(folder) ${resolvedSaved}`, description: 'Use saved output directory', value: 'reuse' },
+                { label: '$(folder-opened) Choose a different directory...', description: 'Browse for a folder', value: 'pick' },
+            ],
+            { placeHolder: 'Output directory', title: 'Publish Settings (2/10)' },
+        );
+        if (!pick) return undefined;
+        if (pick.value === 'reuse') return savedDir;
+    } else {
+        const pick = await vscode.window.showQuickPick(
+            [
+                { label: `$(folder) ${defaultDirName}`, description: `Create ${defaultDirName} relative to notes root`, value: 'default' },
+                { label: '$(folder-opened) Browse...', description: 'Choose an existing directory', value: 'pick' },
+            ],
+            { placeHolder: 'Where should the HTML output be written?', title: 'Publish Settings (2/10)' },
+        );
+        if (!pick) return undefined;
+        if (pick.value === 'default') return defaultDirName;
+    }
+
+    const chosen = await vscode.window.showOpenDialog({
+        canSelectFiles: false,
+        canSelectFolders: true,
+        canSelectMany: false,
+        defaultUri: vscode.Uri.file(notesRoot),
+        openLabel: 'Select Output Directory',
+        title: 'Publish Settings (2/10): Output Directory',
+    });
+    if (!chosen || chosen.length === 0) return undefined;
+    return toRelativePath(notesRoot, chosen[0].fsPath);
+}
+
+/**
+ * Run the HTML conversion CLI for a specific config file.
+ */
+function runConvertForConfig(notesRoot: string, configFilename: string, config: PublishConfig): void {
+    const extensionPath = vscode.extensions.getExtension('appsoftwareltd.as-notes')?.extensionPath
+        ?? path.dirname(path.dirname(__filename));
+    const convertScript = path.join(extensionPath, 'dist', 'convert.js');
+    const configPath = path.join(notesRoot, configFilename);
+
+    // The CLI reads inputDir, outputDir, and all settings from the config file
+    const args: string[] = ['--config', configPath];
+
+    const terminal = vscode.window.createTerminal(`AS Notes: Publish (${configFilename})`);
+    terminal.show();
+    terminal.sendText(`node "${convertScript}" ${args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`);
+
+    const outputDir = config.outputDir || 'output';
+    const resolvedOutput = path.isAbsolute(outputDir) ? outputDir : path.resolve(notesRoot, outputDir);
+    vscode.window.showInformationMessage(`Publishing to ${resolvedOutput}...`);
+}
+
+/**
+ * Run the HTML conversion CLI as a VS Code task.
+ * Discovers publish configs, lets the user pick one (or create new), then publishes.
+ */
+export async function publishToHtml(notesRoot: string): Promise<void> {
+    if (!notesRoot) {
+        vscode.window.showErrorMessage('AS Notes is not initialised. Please initialise a workspace first.');
+        return;
+    }
+
+    const configs = discoverConfigFiles(notesRoot);
+
+    if (configs.length === 0) {
+        // No configs - run wizard to create one
+        const result = await runPublishWizard(notesRoot);
+        if (!result) return;
+        const filename = configFilenameForInputDir(notesRoot, result.inputDir ?? '');
+        writePublishConfig(notesRoot, result, filename);
+        vscode.window.showInformationMessage(`Publish settings saved to ${filename}`);
+
+        // Check output dir is set
+        if (!result.outputDir) {
+            const outputDir = await pickOutputDirectory(notesRoot);
+            if (!outputDir) return;
+            result.outputDir = outputDir;
+            writePublishConfig(notesRoot, result, filename);
+        }
+
+        runConvertForConfig(notesRoot, filename, result);
+        return;
+    }
+
+    // One or more configs - always show a picker
+    const items: { label: string; description: string; value: string }[] = configs.map(c => ({
+        label: `$(file) ${c.filename}`,
+        description: c.config.inputDir ? `Input: ${c.config.inputDir}` : 'Input: notes root',
+        value: c.filename,
+    }));
+    if (configs.length > 1) {
+        items.push({ label: '$(run-all) Publish All', description: 'Publish all configured sites', value: '__all__' });
+    }
+    items.push({ label: '$(add) Create new site config...', description: 'Set up a new publish configuration', value: '__create__' });
+
+    const pick = await vscode.window.showQuickPick(items, {
+        placeHolder: 'Select a publish configuration',
+        title: 'Publish Site',
+    });
+    if (!pick) return;
+
+    if (pick.value === '__create__') {
+        const result = await runPublishWizard(notesRoot);
+        if (!result) return;
+        const filename = configFilenameForInputDir(notesRoot, result.inputDir ?? '');
+        writePublishConfig(notesRoot, result, filename);
+        vscode.window.showInformationMessage(`Publish settings saved to ${filename}`);
+
+        if (!result.outputDir) {
+            const outputDir = await pickOutputDirectory(notesRoot);
+            if (!outputDir) return;
+            result.outputDir = outputDir;
+            writePublishConfig(notesRoot, result, filename);
+        }
+
+        runConvertForConfig(notesRoot, filename, result);
+        return;
+    }
+
+    if (pick.value === '__all__') {
+        for (const { filename, config } of configs) {
+            if (!config.outputDir) {
+                const outputDir = await pickOutputDirectory(notesRoot, config.outputDir);
+                if (!outputDir) continue;
+                config.outputDir = outputDir;
+                writePublishConfig(notesRoot, config, filename);
+            }
+            runConvertForConfig(notesRoot, filename, config);
+        }
+        return;
+    }
+
+    const selected = configs.find(c => c.filename === pick.value);
+    if (!selected) return;
+
+    if (!selected.config.outputDir) {
+        const outputDir = await pickOutputDirectory(notesRoot, selected.config.outputDir);
+        if (!outputDir) return;
+        selected.config.outputDir = outputDir;
+        writePublishConfig(notesRoot, selected.config, selected.filename);
+    }
+
+    runConvertForConfig(notesRoot, selected.filename, selected.config);
+}
+
+/**
+ * Run the publish settings wizard without building.
+ * Discovers existing configs and lets the user edit one or create new.
+ */
+export async function configurePublish(notesRoot: string): Promise<void> {
+    if (!notesRoot) {
+        vscode.window.showErrorMessage('AS Notes is not initialised. Please initialise a workspace first.');
+        return;
+    }
+
+    const configs = discoverConfigFiles(notesRoot);
+
+    if (configs.length === 0) {
+        // No configs - create new
+        const result = await runPublishWizard(notesRoot);
+        if (!result) return;
+        const filename = configFilenameForInputDir(notesRoot, result.inputDir ?? '');
+        writePublishConfig(notesRoot, result, filename);
+        vscode.window.showInformationMessage(`Publish settings saved to ${filename}`);
+        return;
+    }
+
+    // Show picker: edit existing or create new
+    const items: { label: string; description: string; value: string }[] = configs.map(c => ({
+        label: `$(edit) ${c.filename}`,
+        description: c.config.inputDir ? `Input: ${c.config.inputDir}` : 'Input: notes root',
+        value: c.filename,
+    }));
+    items.push({ label: '$(add) Create new site config...', description: 'Set up a new publish configuration', value: '__create__' });
+
+    const pick = await vscode.window.showQuickPick(items, {
+        placeHolder: 'Select a configuration to edit',
+        title: 'Configure Publish Settings',
+    });
+    if (!pick) return;
+
+    if (pick.value === '__create__') {
+        const result = await runPublishWizard(notesRoot);
+        if (!result) return;
+        const filename = configFilenameForInputDir(notesRoot, result.inputDir ?? '');
+        writePublishConfig(notesRoot, result, filename);
+        vscode.window.showInformationMessage(`Publish settings saved to ${filename}`);
+        return;
+    }
+
+    const selected = configs.find(c => c.filename === pick.value);
+    if (!selected) return;
+
+    const result = await runPublishWizard(notesRoot, selected.config);
+    if (!result) return;
+
+    // If inputDir changed, the filename may need to change too
+    const newFilename = configFilenameForInputDir(notesRoot, result.inputDir ?? '');
+    if (newFilename !== selected.filename) {
+        // Delete old config file and write new one
+        const oldPath = path.join(notesRoot, selected.filename);
+        if (fs.existsSync(oldPath)) {
+            fs.unlinkSync(oldPath);
+        }
+    }
+
+    writePublishConfig(notesRoot, result, newFilename);
+    vscode.window.showInformationMessage(`Publish settings saved to ${newFilename}`);
+}
diff --git a/vs-code-extension/src/SlashCommandProvider.ts b/vs-code-extension/src/SlashCommandProvider.ts
index 9fa6126..f8ac12f 100644
--- a/vs-code-extension/src/SlashCommandProvider.ts
+++ b/vs-code-extension/src/SlashCommandProvider.ts
@@ -248,6 +248,60 @@ export class SlashCommandProvider implements vscode.CompletionItemProvider {
         };
         items.push(removeColsLeftItem);
 
+        // ── Publishing slash commands ─────────────────────────────────────
+
+        // ── Public ──────────────────────────────────────────────────────
+        const publicItem = new vscode.CompletionItem('Public', vscode.CompletionItemKind.Property);
+        publicItem.detail = 'Toggle public: true/false in front matter';
+        publicItem.sortText = 'da-publish-public';
+        publicItem.filterText = '/Public';
+        publicItem.insertText = '';
+        publicItem.range = range;
+        publicItem.command = {
+            command: 'as-notes.togglePublic',
+            title: 'Toggle Public',
+        };
+        items.push(publicItem);
+
+        // ── Layout ──────────────────────────────────────────────────────
+        const layoutItem = new vscode.CompletionItem('Layout', vscode.CompletionItemKind.Property);
+        layoutItem.detail = 'Cycle layout: docs/blog/minimal in front matter';
+        layoutItem.sortText = 'db-publish-layout';
+        layoutItem.filterText = '/Layout';
+        layoutItem.insertText = '';
+        layoutItem.range = range;
+        layoutItem.command = {
+            command: 'as-notes.cycleLayout',
+            title: 'Cycle Layout',
+        };
+        items.push(layoutItem);
+
+        // ── Retina ──────────────────────────────────────────────────────
+        const retinaItem = new vscode.CompletionItem('Retina', vscode.CompletionItemKind.Property);
+        retinaItem.detail = 'Toggle retina: true/false in front matter';
+        retinaItem.sortText = 'dc-publish-retina';
+        retinaItem.filterText = '/Retina';
+        retinaItem.insertText = '';
+        retinaItem.range = range;
+        retinaItem.command = {
+            command: 'as-notes.toggleRetina',
+            title: 'Toggle Retina',
+        };
+        items.push(retinaItem);
+
+        // ── Assets ──────────────────────────────────────────────────────
+        const assetsItem = new vscode.CompletionItem('Assets', vscode.CompletionItemKind.Property);
+        assetsItem.detail = 'Toggle assets: true/false in front matter';
+        assetsItem.sortText = 'dd-publish-assets';
+        assetsItem.filterText = '/Assets';
+        assetsItem.insertText = '';
+        assetsItem.range = range;
+        assetsItem.command = {
+            command: 'as-notes.toggleAssets',
+            title: 'Toggle Assets',
+        };
+        items.push(assetsItem);
+
         // ── Card: Entry Date (kanban card files only) ─────────────────────
         const filePath = document.uri.fsPath.replace(/\\/g, '/');
         const isKanbanCardFile = /\/kanban\//.test(filePath) && /\/card_[^/]+\.md$/.test(filePath);
diff --git a/vs-code-extension/src/WikilinkRenameTracker.ts b/vs-code-extension/src/WikilinkRenameTracker.ts
index a58d51b..c0b6587 100644
--- a/vs-code-extension/src/WikilinkRenameTracker.ts
+++ b/vs-code-extension/src/WikilinkRenameTracker.ts
@@ -4,7 +4,7 @@ import { WikilinkFileService } from './WikilinkFileService.js';
 import type { IndexService, LinkRow } from './IndexService.js';
 import type { IndexScanner } from './IndexScanner.js';
 import { sanitiseFileName } from './PathUtils.js';
-import { FrontMatterService } from './FrontMatterService.js';
+import { FrontMatterService } from 'as-notes-common';
 import { toNotesRelativePath } from './NotesRootService.js';
 
 /**
diff --git a/vs-code-extension/src/extension.ts b/vs-code-extension/src/extension.ts
index 4d36501..0626d1a 100644
--- a/vs-code-extension/src/extension.ts
+++ b/vs-code-extension/src/extension.ts
@@ -43,6 +43,7 @@ import { IgnoreService } from './IgnoreService.js';
 import { SlashCommandProvider } from './SlashCommandProvider.js';
 import { openDatePicker } from './DatePickerService.js';
 import { insertTaskDueDate, insertTaskCompletionDate, insertTagAtTaskStart } from './TaskHashtagService.js';
+import { toggleFrontMatterField, cycleFrontMatterField, publishToHtml, configurePublish } from './PublishService.js';
 import { generateTable, addColumns, addRows, formatTable, removeCurrentRow, removeCurrentColumn, removeRowsAbove, removeRowsBelow, removeColumnsRight, removeColumnsLeft } from './TableService.js';
 import { isOnBulletLine, getOutlinerEnterInsert, toggleOutlinerTodoLine, isCodeFenceOpen, getCodeFenceEnterInsert, formatOutlinerPaste, isStandaloneCodeFenceOpen, getStandaloneCodeFenceEnterInsert, isClosingCodeFenceLine, getClosingFenceBulletInsert, isCodeFenceUnbalanced, getMaxOutlinerIndent } from './OutlinerService.js';
 import { KanbanStore } from './KanbanStore.js';
@@ -127,6 +128,12 @@ const FULL_MODE_COMMAND_IDS: string[] = [
     'as-notes.renameKanbanBoard',
     'as-notes.convertTaskToKanbanCard',
     'as-notes.insertTemplate',
+    'as-notes.togglePublic',
+    'as-notes.cycleLayout',
+    'as-notes.toggleRetina',
+    'as-notes.toggleAssets',
+    'as-notes.publishToHtml',
+    'as-notes.configurePublish',
 ];
 
 /** Ignore service for .asnotesignore pattern matching — alive while in full mode. */
@@ -1111,6 +1118,39 @@ async function enterFullMode(
         ),
     );
 
+    // ── Publishing commands ────────────────────────────────────────────
+
+    fullModeDisposables.push(
+        vscode.commands.registerCommand('as-notes.togglePublic', () => {
+            const editor = vscode.window.activeTextEditor;
+            if (editor) { toggleFrontMatterField(editor, 'public', true); }
+        }),
+    );
+    fullModeDisposables.push(
+        vscode.commands.registerCommand('as-notes.cycleLayout', () => {
+            const editor = vscode.window.activeTextEditor;
+            if (editor) { cycleFrontMatterField(editor, 'layout', ['docs', 'blog', 'minimal']); }
+        }),
+    );
+    fullModeDisposables.push(
+        vscode.commands.registerCommand('as-notes.toggleRetina', () => {
+            const editor = vscode.window.activeTextEditor;
+            if (editor) { toggleFrontMatterField(editor, 'retina', true); }
+        }),
+    );
+    fullModeDisposables.push(
+        vscode.commands.registerCommand('as-notes.toggleAssets', () => {
+            const editor = vscode.window.activeTextEditor;
+            if (editor) { toggleFrontMatterField(editor, 'assets', true); }
+        }),
+    );
+    fullModeDisposables.push(
+        vscode.commands.registerCommand('as-notes.publishToHtml', () => publishToHtml(notesRootPaths?.root ?? '')),
+    );
+    fullModeDisposables.push(
+        vscode.commands.registerCommand('as-notes.configurePublish', () => configurePublish(notesRootPaths?.root ?? '')),
+    );
+
     // ── Table commands (Pro) ───────────────────────────────────────────
 
     fullModeDisposables.push(