@janga/norna 0.7.22 → 0.7.24

package/README.md

@@ -76,8 +76,8 @@ site/
 - `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, navigation model,
-  and scroll behavior.
+- `config.yaml` holds the public URL and optional language, source edit link,
+  navigation model, static search, and scroll behavior.
 - `public/` holds static files copied without processing.
 
 Norna validates this structure, processes managed images when needed, and
@@ -93,26 +93,22 @@ builds the generated website into `dist/`.
   reviewed, versioned, and edited with the tools you already use.
 - **A complete publishing path.** The starter includes validation, static
   builds, and an integrated GitHub Pages workflow.
+- **Static search without a service.** One optional setting indexes the
+  completed pages and adds section-level search results.
 
 ## Examples
 
 Every example is built in the repository test suite and published with the
-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/) |
-| Documentation preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-documentation/) | [View files](examples/feature-demos/theme-preset-documentation/) |
-| Project preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-project/) | [View files](examples/feature-demos/theme-preset-project/) |
-| Statement preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-statement/) | [View files](examples/feature-demos/theme-preset-statement/) |
-| Media and surfaces | [Open demo](https://janga.github.io/norna/examples/feature-demos/media-and-surfaces/) | [View files](examples/feature-demos/media-and-surfaces/) |
-| Sitewide content | [Open demo](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](examples/feature-demos/sitewide-content/) |
-
-See [examples/README.md](examples/README.md) for what each example is intended
-to demonstrate and how to run it locally.
+documentation. Start with the
+[single-page](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/)
+and [multi-page](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/)
+dog-shelter sites to inspect complete projects. Use the
+[Theme explorer](https://janga.github.io/norna/examples/theme-presets/) to
+compare presets and palettes against unchanged representative content.
+
+The [example source index](examples/README.md) describes every maintained
+complete site and feature demonstration, links its live result, and shows how
+to run it locally.
 
 ## Is Norna A Good Fit?
 

package/astro.config.mjs

@@ -5,6 +5,7 @@ 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 { nornaCodeFenceTransformer } from './scripts/lib/code-fence-metadata.mjs';
 import { nornaMarkdownRenderPlugin } from './scripts/lib/norna-markdown-render-plugin.mjs';
 import {
 	astroCacheDir,
@@ -136,7 +137,18 @@ export default defineConfig({
 	base: projectConfig.site.basePath,
 	cacheDir: astroCacheDir,
 	markdown: {
+		shikiConfig: {
+			transformers: [nornaCodeFenceTransformer],
+		},
 		processor: satteri({
+			features: {
+				gfm: {
+					footnotes: {
+						label: projectConfig.locale.labels.footnotes,
+						backLabel: projectConfig.locale.labels.footnoteBackReference,
+					},
+				},
+			},
 			mdastPlugins: [nornaMarkdownRenderPlugin],
 		}),
 	},
@@ -144,6 +156,9 @@ export default defineConfig({
 	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
@@ -18,6 +18,7 @@ Commands:
   config:check           Validate site/config.yaml
   content:check          Validate page content and managed image references
   content:sync           Move misplaced Norna-managed images and refresh generated images
+  navigation:review      Review the derived navigation structure without changing files
   theme:presets          List available theme presets and their intended uses
   theme:export           Export a commented theme preset reference
   typography profiles    Show built-in typography profile values
@@ -28,6 +29,7 @@ Commands:
   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
+  page:move              Move a page subtree and update internal links
   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
@@ -139,6 +141,8 @@ try {
 	} else if (command === 'content:sync') {
 		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
 		await runScript('scripts/generate-images.mjs', rest);
+	} else if (command === 'navigation:review') {
+		await runScript('scripts/review-navigation.mjs', rest);
 	} else if (command === 'theme:presets') {
 		await runScript('scripts/list-theme-presets.mjs', rest);
 	} else if (command === 'theme:export') {
@@ -163,6 +167,8 @@ try {
 		await runScript('scripts/init-site.mjs', rest);
 	} else if (command === 'page:add') {
 		await runScript('scripts/add-site-node.mjs', ['page', ...rest]);
+	} else if (command === 'page:move') {
+		await runScript('scripts/move-site-page.mjs', rest);
 	} else if (command === 'category:add') {
 		await runScript('scripts/add-site-node.mjs', ['category', ...rest]);
 	} else if (command === 'build') {

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.22",
+  "version": "0.7.24",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -42,12 +42,15 @@
     "scripts/export-theme-preset.mjs",
     "scripts/generate-images.mjs",
     "scripts/generate-schemas.mjs",
+    "scripts/generate-search-index.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/move-site-page.mjs",
+    "scripts/review-navigation.mjs",
     "scripts/show-typography.mjs",
     "scripts/sync-content-sections.mjs",
     "scripts/sync-site-public.mjs",
@@ -72,6 +75,7 @@
     "config:check": "node bin/norna.mjs config:check",
     "content:check": "node bin/norna.mjs content:check",
     "content:sync": "node bin/norna.mjs content:sync",
+    "navigation:review": "node bin/norna.mjs navigation:review",
     "theme:presets": "node bin/norna.mjs theme:presets",
     "theme:export": "node bin/norna.mjs theme:export",
     "typography:profiles": "node bin/norna.mjs typography profiles",
@@ -88,22 +92,38 @@
     "deploy:watch": "node bin/norna.mjs deploy:watch",
     "doctor": "node bin/norna.mjs doctor",
     "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-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-model-v2 && 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: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": "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:not-found-page && npm run test:site-node-commands && npm run test:page-move && npm run test:navigation-review && npm run test:nested-pages && npm run test:heading-ids && npm run test:navigation-model && npm run test:project-config && npm run test:edit-source-link && npm run test:static-search && 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:not-found-page": "node scripts/test-not-found-page.mjs",
     "test:site-node-commands": "node scripts/test-site-node-commands.mjs",
+    "test:page-move": "node scripts/test-page-move.mjs",
+    "test:navigation-review": "node scripts/test-navigation-review.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:edit-source-link": "node scripts/test-edit-source-link.mjs",
+    "test:static-search": "node scripts/test-static-search.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",
@@ -113,8 +133,11 @@
     "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",
@@ -122,6 +145,7 @@
     "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:placement": "node scripts/test-navigation.mjs --site-dir fixtures/nested-pages/site tests/page-contents-placement.spec.ts",
     "test:navigation:stress": "node scripts/test-navigation.mjs tests/navigation-stress.spec.ts",
     "test:navigation:preview": "node scripts/test-navigation-preview.mjs",
     "package:check": "node scripts/test-package-check.mjs",
@@ -138,6 +162,7 @@
     "astro": "^7.1.3",
     "embla-carousel": "^8.6.0",
     "js-yaml": "^4.3.1",
+    "pagefind": "1.5.2",
     "satteri": "^0.9.1"
   },
   "devDependencies": {

package/schemas/category.schema.json

@@ -6,7 +6,7 @@
       "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.22/docs/pages.md#navigation-categories)"
+      "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.24/docs/pages.md#navigation-categories)"
     }
   },
   "required": [
@@ -16,5 +16,5 @@
   "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.22/docs/pages.md#navigation-categories)"
+  "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.24/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.22/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.24/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.24/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.24/docs/configuration.md#language)"
         },
         {
           "type": "string",
@@ -41,7 +43,27 @@
           "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.22/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.24/docs/configuration.md#language)"
+    },
+    "editLink": {
+      "type": "object",
+      "properties": {
+        "baseUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Absolute edit URL prefix containing the repository, branch, and any repository subdirectory.",
+          "markdownDescription": "```yaml\neditLink:\n  baseUrl: https://github.com/owner/repository/edit/main/\n```\n\nAbsolute edit URL prefix. Include any repository subdirectory and branch in this URL. Norna adds the project-relative path to each page's `content.md` file.\n\n[Edit-link reference](https://github.com/janga/norna/blob/v0.7.24/docs/configuration.md#edit-link)",
+          "examples": [
+            "https://github.com/owner/repository/edit/main/"
+          ]
+        }
+      },
+      "required": [
+        "baseUrl"
+      ],
+      "additionalProperties": false,
+      "description": "Optional base URL for links from rendered pages to their Markdown source files.",
+      "markdownDescription": "```yaml\neditLink:\n  baseUrl: https://github.com/owner/repository/edit/main/\n```\n\nAdds a localized **Edit this page** link from each rendered page to its `content.md` source file. The base URL identifies the repository, branch, and any repository subdirectory; Norna appends the page source path.\n\n[Edit-link reference](https://github.com/janga/norna/blob/v0.7.24/docs/configuration.md#edit-link)"
     },
     "navigation": {
       "type": "object",
@@ -53,46 +75,50 @@
             {
               "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 a flat multi-page site, and a stable left rail throughout a site with listed child pages or categories.",
+              "markdownDescription": "Choose sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a site with listed child pages or categories.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.24/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.24/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.24/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.24/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.22/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.24/docs/pages.md#navigation)",
           "examples": [
             "automatic",
             "sections",
             "top",
             "tree"
           ]
-        },
-        "sectionTracking": {
-          "default": false,
-          "description": "As the reader scrolls in tree navigation, mark the last H2 or H3 that has reached the reading area below the sticky header. The URL and keyboard focus do not change.",
-          "type": "boolean",
-          "markdownDescription": "```yaml\nnavigation:\n  sectionTracking: true\n```\n\nAs the reader scrolls in tree navigation, mark the last H2 or H3 that has reached the reading area below the sticky header. The URL and keyboard focus do not change.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/configuration.md#navigationsectiontracking)",
-          "examples": [
-            true,
-            false
-          ]
         }
       },
       "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.22/docs/pages.md#navigation)"
+      "markdownDescription": "```yaml\nnavigation:\n  mode: automatic\n```\n\nSets the site-wide navigation policy. `automatic` uses sections for one page, top navigation for a flat multi-page site, and a stable left rail throughout a hierarchical site.\n\n[Navigation reference](https://github.com/janga/norna/blob/v0.7.24/docs/pages.md#navigation)"
+    },
+    "search": {
+      "default": false,
+      "description": "Generate a static site search page and Pagefind index. The default is false.",
+      "type": "boolean",
+      "markdownDescription": "```yaml\nsearch: true\n```\n\nGenerates a localized `/search/` page and a static Pagefind index during each build. Search is off by default, and only the search page loads the search JavaScript.\n\n[Search reference](https://github.com/janga/norna/blob/v0.7.24/docs/configuration.md#search)",
+      "examples": [
+        true,
+        false
+      ]
     },
     "scrollBehavior": {
       "default": "instant",
@@ -102,15 +128,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.24/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.24/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.22/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.24/docs/configuration.md#scrollbehavior)",
       "examples": [
         "instant",
         "smooth"
@@ -124,5 +152,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.22/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.24/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.22/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.24/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.24/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.24/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.22/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.24/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.22/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.24/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.22/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.24/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.22/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.24/docs/content.md#page-title-and-frontmatter)"
 }