Static site publishing

.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

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "as-notes.rootDirectory": "docs-src",
+    "markdown.copyFiles.destination": {
+        "**/*.md": "/docs-src/assets/images/${fileName}"
+    }
+}

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.

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.