@janga/norna 0.7.18 → 0.7.23

package/README.md

@@ -13,7 +13,7 @@ than a general-purpose site generator: you describe the site instead of
 implementing a new presentation layer for every project.
 
 [Documentation](https://janga.github.io/norna/) |
-[Five-minute tutorial](docs/getting-started.md) |
+[Getting started](https://janga.github.io/norna/getting-started/install-norna/) |
 [Live examples](https://janga.github.io/norna/examples/) |
 [npm package](https://www.npmjs.com/package/@janga/norna)
 
@@ -37,8 +37,9 @@ Open the URL printed by the development server, then edit the files under
 `site/`. The generated project pins its Norna version and includes the npm
 scripts and GitHub Pages workflow needed to check, build, and publish it.
 
-Follow the [five-minute tutorial](docs/getting-started.md) for a first edit and
-verified build.
+Continue with the illustrated
+[Getting Started](https://janga.github.io/norna/getting-started/install-norna/) guide to see
+how page content, files, navigation, and rendered output fit together.
 
 For shorter commands, install the launcher globally with
 `npm install --global @janga/norna@latest`. You can then use `norna dev`,
@@ -56,20 +57,27 @@ site/
 |   |-- 000-home/
 |   |   |-- content.md
 |   |   `-- images/
-|   `-- 010-guide/
-|       |-- content.md
+|   `-- 010-guides/
+|       |-- category.yaml
 |       `-- pages/
 |           `-- 010-installation/
+|               |-- content.md
+|               `-- images/
 `-- public/
 ```
 
 - `pages/000-home/content.md` is the required homepage at `/`.
-- Other top-level directories under `pages/` are global navigation roots.
-- A page may contain local images, limited presentation settings, and nested
-  child pages under its own `pages/` directory.
+- Every other ordered directory under `pages/` contains either `content.md` for
+  a routable page or `category.yaml` for a navigation-only group.
+- A page may contain local images. A page or category may contain limited
+  presentation settings and nested entries under its own `pages/` directory.
+- Category ids remain in child URLs, but categories do not generate pages of
+  their own.
 - `theme.yaml` normally selects one complete visual preset.
-- `sitewide-content.yaml` holds shared logo display settings, banners, and footer content.
-- `config.yaml` holds the public URL and optional language and scroll behavior.
+- `sitewide-content.yaml` holds shared logo display settings, banners, and
+  footer content.
+- `config.yaml` holds the public URL and optional language, navigation model,
+  and scroll behavior.
 - `public/` holds static files copied without processing.
 
 Norna validates this structure, processes managed images when needed, and
@@ -93,6 +101,7 @@ documentation.
 
 | Example | Live site | Source |
 | --- | --- | --- |
+| Theme explorer | [Combine presets and palettes](https://janga.github.io/norna/examples/theme-presets/) | See the four preset sources below |
 | Dog shelter, single page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/) | [View files](examples/complete-sites/dog-shelter-single-page/) |
 | Dog shelter, multi-page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](examples/complete-sites/dog-shelter-multi-page/) |
 | Portfolio preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-portfolio/) | [View files](examples/feature-demos/theme-preset-portfolio/) |
@@ -132,11 +141,12 @@ engine diagnostics, not for ordinary editing and local preview. See
 
 ## Documentation
 
-- [Five-minute tutorial](docs/getting-started.md)
+- [Getting Started](https://janga.github.io/norna/getting-started/install-norna/)
 - [Site files](docs/site-files.md)
+- [Upgrading an existing site](docs/upgrading.md)
 - [Task-oriented documentation map](docs/README.md)
 - [Common workflows](docs/README.md#common-workflows)
-- [Concepts and explanation](docs/README.md#concepts-and-explanation)
+- [Explanation and JavaScript boundaries](docs/README.md#explanation)
 - [Command and platform reference](docs/README.md#command-and-platform-reference)
 - [Troubleshooting](docs/README.md#troubleshooting)
 - [AI-readable documentation index](https://janga.github.io/norna/llms.txt)

package/astro.config.mjs

@@ -3,7 +3,9 @@ import { execFile } from 'node:child_process';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
 import { getBasePathRedirectLocation } from './scripts/lib/base-path-redirect.mjs';
+import { nornaMarkdownRenderPlugin } from './scripts/lib/norna-markdown-render-plugin.mjs';
 import {
 	astroCacheDir,
 	astroDistDir,
@@ -70,6 +72,7 @@ const nornaGeneratedImagesWatcher = () => ({
 			sitePagesDir,
 		].map((watchedPath) => path.resolve(watchedPath));
 		let refreshTimer;
+		let structureReloadTimer;
 		let refreshPromise = Promise.resolve();
 
 		const isRelevantSourcePath = (changedPath) => {
@@ -99,6 +102,17 @@ const nornaGeneratedImagesWatcher = () => ({
 			refreshTimer = setTimeout(refreshImages, 250);
 		};
 
+		const scheduleStructureReload = (changedPath) => {
+			if (!isRelevantSourcePath(changedPath)) return;
+			const filename = path.basename(changedPath);
+			if (filename !== 'category.yaml' && filename !== 'theme.yaml') return;
+
+			clearTimeout(structureReloadTimer);
+			structureReloadTimer = setTimeout(() => {
+				server.ws.send({ type: 'full-reload' });
+			}, 300);
+		};
+
 		server.watcher.add(manifestPath);
 		server.watcher.add(watchedSourcePaths);
 		server.watcher.on('change', (changedPath) => {
@@ -111,6 +125,9 @@ const nornaGeneratedImagesWatcher = () => ({
 		server.watcher.on('unlink', scheduleRefreshImages);
 		server.watcher.on('addDir', scheduleRefreshImages);
 		server.watcher.on('unlinkDir', scheduleRefreshImages);
+		server.watcher.on('add', scheduleStructureReload);
+		server.watcher.on('change', scheduleStructureReload);
+		server.watcher.on('unlink', scheduleStructureReload);
 	},
 });
 
@@ -118,10 +135,18 @@ const nornaGeneratedImagesWatcher = () => ({
 export default defineConfig({
 	base: projectConfig.site.basePath,
 	cacheDir: astroCacheDir,
+	markdown: {
+		processor: satteri({
+			mdastPlugins: [nornaMarkdownRenderPlugin],
+		}),
+	},
 	outDir: astroDistDir,
 	publicDir: astroPublicDir,
 	srcDir: path.join(engineRoot, 'src'),
 	vite: {
+		server: {
+			strictPort: true,
+		},
 		plugins: [nornaBasePathRedirect(), nornaGeneratedImagesWatcher()],
 	},
 });

package/bin/norna-cli.mjs

@@ -8,8 +8,8 @@ const usage = `
 Usage: norna <command> [options]
 
 Commands:
-  dev:local              Start local Astro dev server
-  dev:lan                Start dev server for this local network
+  dev:local [--kill]     Start local Astro dev server on the configured port
+  dev:lan [--kill]       Start LAN dev server on the configured port
   dev:restart            Restart local Astro dev server
   dev:status             Show local dev server status
   dev:logs               Show local dev server logs
@@ -27,6 +27,8 @@ Commands:
   engine:update          Update @janga/norna in a site repository
   engine:version         Show installed engine and Astro versions
   init                   Create a new site project from the starter
+  page:add               Add a page to the site page tree
+  category:add           Add a non-routable category to the site page tree
   build                  Build the selected site
   build:local            Build and restart local dev server
   deploy                 Build and deploy committed branch
@@ -159,6 +161,10 @@ try {
 		await runScript('scripts/engine-version.mjs', rest);
 	} else if (command === 'init') {
 		await runScript('scripts/init-site.mjs', rest);
+	} else if (command === 'page:add') {
+		await runScript('scripts/add-site-node.mjs', ['page', ...rest]);
+	} else if (command === 'category:add') {
+		await runScript('scripts/add-site-node.mjs', ['category', ...rest]);
 	} else if (command === 'build') {
 		await runBuild();
 	} else if (command === 'build:local') {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@janga/norna",
   "description": "An opinionated CLI for building responsive websites from Markdown, images, and theme presets.",
   "type": "module",
-  "version": "0.7.18",
+  "version": "0.7.23",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -26,15 +26,33 @@
   "files": [
     "astro.config.mjs",
     "bin/",
-    "docs/",
-    "examples/",
-    "fixtures/",
-    "scripts/",
     "schemas/",
     "src/",
-    "starters/",
-    "!**/.norna/public/",
-    "tsconfig.json",
+    "starters/basic/",
+    "!starters/basic/.astro/",
+    "!starters/basic/node_modules/",
+    "!starters/basic/site/.norna/",
+    "scripts/build-site.mjs",
+    "scripts/add-site-node.mjs",
+    "scripts/check-config.mjs",
+    "scripts/deploy-site.mjs",
+    "scripts/dev-local.mjs",
+    "scripts/doctor.mjs",
+    "scripts/engine-version.mjs",
+    "scripts/export-theme-preset.mjs",
+    "scripts/generate-images.mjs",
+    "scripts/generate-schemas.mjs",
+    "scripts/init-site.mjs",
+    "scripts/lib/",
+    "!scripts/lib/documentation-preset-candidates.mjs",
+    "!scripts/lib/example-sites.mjs",
+    "!scripts/lib/git-status.mjs",
+    "scripts/list-theme-presets.mjs",
+    "scripts/show-typography.mjs",
+    "scripts/sync-content-sections.mjs",
+    "scripts/sync-site-public.mjs",
+    "scripts/update-engine.mjs",
+    "scripts/watch-pages-deploy.mjs",
     "README.md"
   ],
   "publishConfig": {
@@ -69,27 +87,53 @@
     "deploy:commit": "node bin/norna.mjs deploy:commit",
     "deploy:watch": "node bin/norna.mjs deploy:watch",
     "doctor": "node bin/norna.mjs doctor",
-    "demo:build": "node bin/norna.mjs --site-dir examples/feature-demos/media-and-surfaces/site build",
-    "test": "npm run schemas:check && npm run test:schemas && npm run test:page-model && npm run test:nested-pages && npm run test:heading-ids && npm run test:navigation-model && npm run test:project-config && npm run test:editor-language && npm run test:content-check && npm run test:content-model-v2 && npm run test:theme-presets && npm run test:site-public && npm run test:cli-discovery && npm run test:engine-commands && npm run test:documentation && npm run test:ci-lockfile && npm run test:banner-visibility && npm run test:client-javascript && npm run test:fixture:build && npm run test:examples && npm run package:check",
-    "test:fixture:build": "node bin/norna.mjs --site-dir fixtures/basic/site build",
+    "demo:build": "node scripts/build-demo.mjs",
+    "test": "npm run schemas:check && npm run test:dead-code && npm run test:schemas && npm run test:page-model && npm run test:page-markdown && npm run test:site-links && npm run test:page-aliases && npm run test:sitemap && npm run test:site-node-commands && npm run test:nested-pages && npm run test:heading-ids && npm run test:navigation-model && npm run test:project-config && npm run test:editor-language && npm run test:content-check && npm run test:content-sync-plan && npm run test:content-model && npm run test:theme-presets && npm run test:presentation-contract && npm run test:preset-baselines && npm run test:documentation-preset-review && npm run test:site-public && npm run test:cli-discovery && npm run test:dev-local && npm run test:engine-commands && npm run test:documentation && npm run test:ci-lockfile && npm run test:banner-visibility && npm run test:client-javascript && npm run test:fixture:build && npm run test:examples && npm run package:check",
+    "test:fixture:build": "node scripts/test-basic-fixture-build.mjs",
     "test:examples": "node scripts/test-examples.mjs",
     "test:page-model": "node scripts/test-page-model.mjs",
+    "test:page-markdown": "node scripts/test-page-markdown.mjs",
+    "test:site-links": "node scripts/test-site-link-graph.mjs",
+    "test:page-aliases": "node scripts/test-page-aliases.mjs",
+    "test:sitemap": "node scripts/test-sitemap.mjs",
+    "test:site-node-commands": "node scripts/test-site-node-commands.mjs",
     "test:nested-pages": "node scripts/test-nested-pages.mjs",
     "test:heading-ids": "node scripts/test-heading-ids.mjs",
     "test:navigation-model": "node scripts/test-navigation-model.mjs",
     "test:schemas": "node scripts/test-schemas.mjs",
     "test:project-config": "node scripts/test-project-config.mjs",
     "test:content-check": "node scripts/test-content-check.mjs",
-    "test:content-model-v2": "node scripts/test-content-model-v2.mjs",
+    "test:content-sync-plan": "node scripts/test-content-sync-plan.mjs",
+    "test:content-model": "npm run test:page-content && npm run test:managed-media && npm run test:content-sync && npm run test:markdown-constructs",
+    "test:page-content": "node scripts/test-page-content.mjs",
+    "test:managed-media": "node scripts/test-managed-media.mjs",
+    "test:content-sync": "node scripts/test-content-sync.mjs",
+    "test:markdown-constructs": "node scripts/test-markdown-constructs.mjs",
     "test:theme-presets": "node scripts/test-theme-presets.mjs",
+    "test:presentation-contract": "node scripts/test-presentation-contract.mjs",
+    "test:presentation:browser": "node scripts/test-navigation.mjs --site-dir fixtures/preset-baseline/site tests/presentation-contract.spec.ts",
+    "test:navigation-surfaces:browser": "npm run test:navigation-surfaces:top && npm run test:navigation-surfaces:tree",
+    "test:navigation-surfaces:top": "node scripts/test-navigation.mjs --site-dir fixtures/content-model-v2/site tests/navigation-surfaces-top.spec.ts",
+    "test:navigation-surfaces:tree": "node scripts/test-navigation.mjs --site-dir fixtures/preset-baseline/site tests/presentation-contract.spec.ts",
+    "test:preset-baselines": "node scripts/test-preset-baselines.mjs",
+    "test:documentation-preset-review": "node scripts/test-documentation-preset-review.mjs",
+    "preset:baselines:capture": "node scripts/test-preset-baselines.mjs --capture",
+    "preset:documentation:review": "node scripts/review-documentation-preset.mjs",
+    "preset:documentation:review:build": "node scripts/review-documentation-preset.mjs --build-only",
+    "palette:review": "node scripts/review-documentation-preset.mjs --palettes",
+    "palette:review:build": "node scripts/review-documentation-preset.mjs --palettes --build-only",
     "test:site-public": "node scripts/test-site-public.mjs",
     "test:cli-discovery": "node scripts/test-cli-discovery.mjs",
+    "test:dev-local": "node scripts/test-dev-local.mjs",
     "test:engine-commands": "node scripts/test-engine-commands.mjs",
     "test:editor-language": "node scripts/test-editor-language-service.mjs && npm --prefix editors/vscode run check",
+    "test:editor-integration": "npm --prefix editors/vscode run test:integration",
+    "test:editor-integration:minimum": "npm --prefix editors/vscode run test:integration:minimum",
     "test:documentation": "node scripts/test-documentation.mjs",
     "test:ci-lockfile": "node scripts/test-ci-lockfile.mjs",
     "test:banner-visibility": "node scripts/test-banner-visibility.mjs",
     "test:client-javascript": "node scripts/test-client-javascript.mjs",
+    "test:dead-code": "knip --include files,exports",
     "test:navigation": "node scripts/test-navigation.mjs",
     "test:navigation:tree": "node scripts/test-navigation.mjs --site-dir fixtures/nested-pages/site tests/navigation-tree.spec.ts",
     "test:navigation:stress": "node scripts/test-navigation.mjs tests/navigation-stress.spec.ts",
@@ -103,12 +147,15 @@
     "astro": "node bin/norna.mjs astro"
   },
   "dependencies": {
+    "@astrojs/markdown-satteri": "0.3.4",
+    "@lucide/astro": "1.34.0",
     "astro": "^7.1.3",
     "embla-carousel": "^8.6.0",
     "js-yaml": "^4.3.1",
     "satteri": "^0.9.1"
   },
   "devDependencies": {
-    "@playwright/test": "^1.61.1"
+    "@playwright/test": "^1.61.1",
+    "knip": "6.33.0"
   }
 }

package/schemas/category.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Navigation label for this non-routable page category.",
+      "markdownDescription": "```yaml\nlabel: Guides\n```\n\nThe category label shown in global navigation, tree navigation, mobile navigation, and breadcrumbs.\n\n[Navigation category reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation-categories)"
+    }
+  },
+  "required": [
+    "label"
+  ],
+  "additionalProperties": false,
+  "description": "A non-routable navigation category containing child pages.",
+  "$id": "https://janga.github.io/norna/schemas/category.schema.json",
+  "title": "Norna page category",
+  "markdownDescription": "```yaml\nlabel: Guides\n```\n\n`category.yaml` creates a navigation-only group for child pages. It has no page content and produces no URL of its own.\n\n[Navigation category reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation-categories)"
+}

package/schemas/config.schema.json

@@ -6,7 +6,7 @@
       "type": "string",
       "format": "uri",
       "description": "Absolute public URL for the built site.",
-      "markdownDescription": "```yaml\nurl: https://example.com/\n```\n\nThe absolute public URL. Its path also determines the base path for generated links and assets.\n\n[Public URL reference](https://github.com/janga/norna/blob/v0.7.18/docs/configuration.md#url)",
+      "markdownDescription": "```yaml\nurl: https://example.com/\n```\n\nThe absolute public URL. Its path also determines the base path for generated links and assets.\n\n[Public URL reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#url)",
       "examples": [
         "https://example.com/",
         "https://owner.github.io/repository-name/"
@@ -27,12 +27,14 @@
         {
           "const": "en",
           "title": "English",
-          "description": "Use Norna's built-in English interface text."
+          "description": "Use Norna's built-in English interface text.",
+          "markdownDescription": "Use Norna's built-in English interface text.\n\n[Language reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#language)"
         },
         {
           "const": "sv",
           "title": "Swedish",
-          "description": "Use Norna's built-in Swedish interface text."
+          "description": "Use Norna's built-in Swedish interface text.",
+          "markdownDescription": "Use Norna's built-in Swedish interface text.\n\n[Language reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#language)"
         },
         {
           "type": "string",
@@ -41,7 +43,7 @@
           "description": "Use an English or Swedish regional language tag such as en-GB or sv-SE."
         }
       ],
-      "markdownDescription": "```yaml\nlanguage: en-GB\n```\n\nSets the page language and selects Norna's built-in English or Swedish interface text. The default is `en`.\n\n[Language reference](https://github.com/janga/norna/blob/v0.7.18/docs/configuration.md#language)"
+      "markdownDescription": "```yaml\nlanguage: en-GB\n```\n\nSets the page language and selects Norna's built-in English or Swedish interface text. The default is `en`.\n\n[Language reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#language)"
     },
     "navigation": {
       "type": "object",
@@ -53,25 +55,29 @@
             {
               "const": "automatic",
               "title": "Automatic",
-              "description": "Choose sections for one page, top navigation for a shallow multi-page site, and tree navigation for deeper content."
+              "description": "Choose sections for one page, top navigation for Home and independent top-level pages, and tree navigation inside branches with listed children or categories.",
+              "markdownDescription": "Choose sections for one page, top navigation for Home and independent top-level pages, and tree navigation inside branches with listed children or categories.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)"
             },
             {
               "const": "sections",
               "title": "Sections",
-              "description": "Navigate the sections of the current page."
+              "description": "Navigate the sections of the current page.",
+              "markdownDescription": "Navigate the sections of the current page.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)"
             },
             {
               "const": "top",
               "title": "Top",
-              "description": "Use pages in the top navigation and sections below them."
+              "description": "Use pages in the top navigation and sections below them.",
+              "markdownDescription": "Use pages in the top navigation and sections below them.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)"
             },
             {
               "const": "tree",
               "title": "Tree",
-              "description": "Use a hierarchical site-wide navigation tree."
+              "description": "Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.",
+              "markdownDescription": "Use a left page rail and a separate right H2/H3 contents rail where the page has enough headings.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)"
             }
           ],
-          "markdownDescription": "```yaml\nnavigation:\n  mode: automatic\n```\n\nNavigation model. Omit this to let Norna choose from the site structure.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.18/docs/pages.md#navigation)",
+          "markdownDescription": "```yaml\nnavigation:\n  mode: automatic\n```\n\nNavigation model. Omit this to let Norna choose from the site structure.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)",
           "examples": [
             "automatic",
             "sections",
@@ -82,7 +88,7 @@
       },
       "additionalProperties": false,
       "description": "Site-wide navigation behavior.",
-      "markdownDescription": "```yaml\nnavigation:\n  mode: automatic\n```\n\nSets one navigation model for the complete site. `automatic` selects from the page hierarchy.\n\n[Navigation reference](https://github.com/janga/norna/blob/v0.7.18/docs/pages.md#navigation)"
+      "markdownDescription": "```yaml\nnavigation:\n  mode: automatic\n```\n\nSets the site-wide navigation policy. `automatic` selects an effective mode for each page from its active top-level branch.\n\n[Navigation reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)"
     },
     "scrollBehavior": {
       "default": "instant",
@@ -92,15 +98,17 @@
         {
           "const": "instant",
           "title": "Instant",
-          "description": "Jump directly to anchors without animated scrolling. This is the default."
+          "description": "Jump directly to anchors without animated scrolling. This is the default.",
+          "markdownDescription": "Jump directly to anchors without animated scrolling. This is the default.\n\n[Scroll behavior reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#scrollbehavior)"
         },
         {
           "const": "smooth",
           "title": "Browser smooth",
-          "description": "Use the browser's native smooth scrolling for anchor navigation."
+          "description": "Use the browser's native smooth scrolling for anchor navigation.",
+          "markdownDescription": "Use the browser's native smooth scrolling for anchor navigation.\n\n[Scroll behavior reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#scrollbehavior)"
         }
       ],
-      "markdownDescription": "```yaml\nscrollBehavior: smooth\n```\n\nControls same-page anchor movement. `instant` is the default; `smooth` uses the browser's native smooth scrolling.\n\n[Scroll behavior reference](https://github.com/janga/norna/blob/v0.7.18/docs/configuration.md#scrollbehavior)",
+      "markdownDescription": "```yaml\nscrollBehavior: smooth\n```\n\nControls same-page anchor movement. `instant` is the default; `smooth` uses the browser's native smooth scrolling.\n\n[Scroll behavior reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md#scrollbehavior)",
       "examples": [
         "instant",
         "smooth"
@@ -114,5 +122,5 @@
   "description": "Technical settings for one Norna site. Additional pages cannot provide technical configuration.",
   "$id": "https://janga.github.io/norna/schemas/config.schema.json",
   "title": "Norna site configuration",
-  "markdownDescription": "```yaml\nurl: https://example.com/\n```\n\n`config.yaml` contains the few technical settings shared by the complete site.\n\n[Configuration reference](https://github.com/janga/norna/blob/v0.7.18/docs/configuration.md)"
+  "markdownDescription": "```yaml\nurl: https://example.com/\n```\n\n`config.yaml` contains the few technical settings shared by the complete site.\n\n[Configuration reference](https://github.com/janga/norna/blob/v0.7.23/docs/configuration.md)"
 }

package/schemas/content-frontmatter.schema.json

@@ -9,15 +9,35 @@
           "description": "Optional page-specific meta description.",
           "type": "string",
           "minLength": 1,
-          "markdownDescription": "```yaml\npage:\n  description: About this project.\n```\n\nAn optional page-specific description rendered as `<meta name=\"description\">`. It is not visible in page content.\n\n[Page title and frontmatter reference](https://github.com/janga/norna/blob/v0.7.18/docs/content.md#page-title-and-frontmatter)",
+          "markdownDescription": "```yaml\npage:\n  description: About this project.\n```\n\nAn optional page-specific description rendered as `<meta name=\"description\">`. It is not visible in page content.\n\n[Page title and frontmatter reference](https://github.com/janga/norna/blob/v0.7.23/docs/content.md#page-title-and-frontmatter)",
           "examples": [
             "About this project."
           ]
+        },
+        "aliases": {
+          "description": "Previous site-relative URLs that permanently identify this page. The current page is always the target.",
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\\/)+$",
+            "description": "Previous site-relative URL that permanently identifies this page.",
+            "markdownDescription": "```yaml\npage:\n  aliases:\n    - /old-about/\n```\n\nUse a previous Norna page URL. Start and end with `/`; use lowercase ASCII letters, numbers, and single hyphens; do not include the configured base path, a query string, or a fragment.\n\n[Alias path rules](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#preserve-old-page-urls)",
+            "examples": [
+              "/old-about/"
+            ]
+          },
+          "markdownDescription": "```yaml\npage:\n  aliases:\n    - /old-about/\n```\n\nLists previous site-relative URLs that permanently identify this page. The page containing the list is always the target. Paths omit the configured base path and are excluded from the sitemap.\n\n[Preserve old page URLs](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#preserve-old-page-urls)",
+          "examples": [
+            [
+              "/old-about/"
+            ]
+          ]
         }
       },
       "additionalProperties": false,
       "description": "Optional metadata for this homepage or additional page. The Markdown H1 supplies the page title.",
-      "markdownDescription": "```yaml\npage:\n  description: About this project.\n```\n\nContains optional metadata for the current homepage or additional page. The Markdown H1 supplies its title.\n\n[Page title and frontmatter reference](https://github.com/janga/norna/blob/v0.7.18/docs/content.md#page-title-and-frontmatter)"
+      "markdownDescription": "```yaml\npage:\n  description: About this project.\n  aliases:\n    - /old-about/\n```\n\nContains optional metadata for the current homepage or additional page. The Markdown H1 supplies its title. An alias records an old URL for this same page.\n\n[Page title and frontmatter reference](https://github.com/janga/norna/blob/v0.7.23/docs/content.md#page-title-and-frontmatter)"
     },
     "navigation": {
       "description": "Optional navigation metadata for this page.",
@@ -27,7 +47,7 @@
           "default": true,
           "description": "List this page in site navigation. The page remains public when false.",
           "type": "boolean",
-          "markdownDescription": "```yaml\nnavigation:\n  listed: false\n```\n\nList this page in site navigation. The page remains public when false.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.18/docs/pages.md#navigation)",
+          "markdownDescription": "```yaml\nnavigation:\n  listed: false\n```\n\nList this page in site navigation. The page remains public when false.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)",
           "examples": [
             true,
             false
@@ -35,12 +55,12 @@
         }
       },
       "additionalProperties": false,
-      "markdownDescription": "```yaml\nnavigation:\n  listed: false\n```\n\nOptionally excludes an additional page from site navigation without removing its public URL.\n\n[Site navigation reference](https://github.com/janga/norna/blob/v0.7.18/docs/pages.md#navigation)"
+      "markdownDescription": "```yaml\nnavigation:\n  listed: false\n```\n\nOptionally excludes an additional page from site navigation without removing its public URL.\n\n[Site navigation reference](https://github.com/janga/norna/blob/v0.7.23/docs/pages.md#navigation)"
     }
   },
   "additionalProperties": false,
   "description": "Frontmatter for a homepage or additional page content.md file.",
   "$id": "https://janga.github.io/norna/schemas/content-frontmatter.schema.json",
   "title": "Norna page frontmatter",
-  "markdownDescription": "```yaml\n---\npage:\n  description: About this project.\n---\n```\n\nContent frontmatter is optional. Write the page title as the single Markdown H1; use frontmatter only for optional metadata or navigation settings.\n\n[Page title and frontmatter reference](https://github.com/janga/norna/blob/v0.7.18/docs/content.md#page-title-and-frontmatter)"
+  "markdownDescription": "```yaml\n---\npage:\n  description: About this project.\n---\n```\n\nContent frontmatter is optional. Write the page title as the single Markdown H1; use frontmatter only for optional metadata or navigation settings.\n\n[Page title and frontmatter reference](https://github.com/janga/norna/blob/v0.7.23/docs/content.md#page-title-and-frontmatter)"
 }

package/schemas/manifest.json

@@ -1,7 +1,8 @@
 {
   "editorApiVersion": 1,
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "files": {
+    "category": "category.schema.json",
     "config": "config.schema.json",
     "contentFrontmatter": "content-frontmatter.schema.json",
     "sitewideContent": "sitewide-content.schema.json",