@janga/norna 0.7.22 → 0.7.23

package/astro.config.mjs

@@ -144,6 +144,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

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.23",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -88,11 +88,14 @@
     "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: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",
@@ -100,10 +103,18 @@
     "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",
@@ -113,8 +124,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",

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.23/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.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.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.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.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.23/docs/configuration.md#language)"
     },
     "navigation": {
       "type": "object",
@@ -53,46 +55,40 @@
             {
               "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.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.23/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` 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",
@@ -102,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.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.23/docs/configuration.md#scrollbehavior)",
       "examples": [
         "instant",
         "smooth"
@@ -124,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.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.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.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.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.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.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.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.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.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.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.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.23/docs/content.md#page-title-and-frontmatter)"
 }

package/schemas/page-theme.schema.json

@@ -12,20 +12,23 @@
             {
               "const": "compact",
               "title": "Compact",
-              "description": "Use restrained spacing between sections and structured blocks."
+              "description": "Use restrained spacing between sections and structured blocks.",
+              "markdownDescription": "Use restrained spacing between sections and structured blocks.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             },
             {
               "const": "normal",
               "title": "Normal",
-              "description": "Use balanced content spacing."
+              "description": "Use balanced content spacing.",
+              "markdownDescription": "Use balanced content spacing.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             },
             {
               "const": "spacious",
               "title": "Spacious",
-              "description": "Use more expansive spacing between sections and structured blocks."
+              "description": "Use more expansive spacing between sections and structured blocks.",
+              "markdownDescription": "Use more expansive spacing between sections and structured blocks.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             }
           ],
-          "markdownDescription": "```yaml\nlayout:\n  contentSpacing: compact\n```\n\nPage content spacing. Descendant pages inherit this value.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#page-themes)",
+          "markdownDescription": "```yaml\nlayout:\n  contentSpacing: compact\n```\n\nPage content spacing. Descendant pages inherit this value.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)",
           "examples": [
             "compact",
             "normal",
@@ -39,20 +42,23 @@
             {
               "const": "narrow",
               "title": "Narrow",
-              "description": "Use a shorter line length suited to reading-focused text."
+              "description": "Use a shorter line length suited to reading-focused text.",
+              "markdownDescription": "Use a shorter line length suited to reading-focused text.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             },
             {
               "const": "normal",
               "title": "Normal",
-              "description": "Use the balanced default line length."
+              "description": "Use the balanced default line length.",
+              "markdownDescription": "Use the balanced default line length.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             },
             {
               "const": "wide",
               "title": "Wide",
-              "description": "Allow body text to use more horizontal space."
+              "description": "Allow body text to use more horizontal space.",
+              "markdownDescription": "Allow body text to use more horizontal space.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             }
           ],
-          "markdownDescription": "```yaml\nlayout:\n  textWidth: narrow\n```\n\nBody-text line length. Descendant pages inherit this value.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#page-themes)",
+          "markdownDescription": "```yaml\nlayout:\n  textWidth: narrow\n```\n\nBody-text line length. Descendant pages inherit this value.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)",
           "examples": [
             "narrow",
             "normal",
@@ -62,16 +68,35 @@
       },
       "additionalProperties": false,
       "description": "Page-local layout settings inherited by descendant pages.",
-      "markdownDescription": "```yaml\nlayout:\n  textWidth: narrow\n  contentSpacing: compact\n```\n\nAdjusts body-text line length and vertical content spacing for pages below this directory.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#page-themes)"
+      "markdownDescription": "```yaml\nlayout:\n  textWidth: narrow\n  contentSpacing: compact\n```\n\nAdjusts body-text line length and vertical content spacing for pages below this directory.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
     },
     "images": {
       "type": "object",
       "properties": {
+        "presentation": {
+          "description": "Managed-image presentation method. Omit this to keep the selected preset or inherited page setting.",
+          "type": "string",
+          "oneOf": [
+            {
+              "const": "prose-aligned",
+              "title": "Prose-aligned",
+              "description": "Start managed images and captions at the body-text edge and size them from the page content area.",
+              "markdownDescription": "Start managed images and captions at the body-text edge and size them from the page content area.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
+            },
+            {
+              "const": "centered-fit",
+              "title": "Centered fit",
+              "description": "Center managed images and captions in the page media area and constrain them by available width and viewport height.",
+              "markdownDescription": "Center managed images and captions in the page media area and constrain them by available width and viewport height.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
+            }
+          ],
+          "markdownDescription": "```yaml\nimages:\n  presentation: prose-aligned\n```\n\nManaged-image presentation method. Omit this to keep the selected preset or inherited page setting.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
+        },
         "width": {
           "description": "Maximum managed-image width. Omit this to keep the selected preset.",
           "type": "string",
           "pattern": "^(?:0|(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)|clamp\\(\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*,\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*,\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*\\))$",
-          "markdownDescription": "```yaml\nimages:\n  width: 900px\n```\n\nMaximum managed-image width. Omit this to keep the selected preset.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+          "markdownDescription": "```yaml\nimages:\n  width: 900px\n```\n\nMaximum managed-image width. Omit this to keep the selected preset.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
         },
         "maxAvailableWidthPercent": {
           "description": "Maximum percentage of available horizontal space used by managed images.",
@@ -89,14 +114,14 @@
                   "exclusiveMinimum": 0,
                   "maximum": 100,
                   "description": "Percentage used on wider screens.",
-                  "markdownDescription": "```yaml\nimages:\n  maxAvailableWidthPercent:\n    desktop: 100\n```\n\nPercentage used on wider screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+                  "markdownDescription": "```yaml\nimages:\n  maxAvailableWidthPercent:\n    desktop: 100\n```\n\nPercentage used on wider screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
                 },
                 "mobile": {
                   "type": "number",
                   "exclusiveMinimum": 0,
                   "maximum": 100,
                   "description": "Percentage used on narrow screens.",
-                  "markdownDescription": "```yaml\nimages:\n  maxAvailableWidthPercent:\n    mobile: 100\n```\n\nPercentage used on narrow screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+                  "markdownDescription": "```yaml\nimages:\n  maxAvailableWidthPercent:\n    mobile: 100\n```\n\nPercentage used on narrow screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
                 }
               },
               "required": [
@@ -106,10 +131,10 @@
               "additionalProperties": false
             }
           ],
-          "markdownDescription": "```yaml\nimages:\n  maxAvailableWidthPercent:\n    desktop: 100\n    mobile: 100\n```\n\nMaximum percentage of available horizontal space used by managed images.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+          "markdownDescription": "```yaml\nimages:\n  maxAvailableWidthPercent:\n    desktop: 100\n    mobile: 100\n```\n\nMaximum percentage of available horizontal space used by managed images.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
         },
         "maxAvailableHeightPercent": {
-          "description": "Maximum percentage of viewport height used by managed images.",
+          "description": "Maximum percentage of viewport height used by centered-fit images. This setting is unavailable with prose-aligned presentation.",
           "anyOf": [
             {
               "type": "number",
@@ -124,14 +149,14 @@
                   "exclusiveMinimum": 0,
                   "maximum": 100,
                   "description": "Percentage used on wider screens.",
-                  "markdownDescription": "```yaml\nimages:\n  maxAvailableHeightPercent:\n    desktop: 74\n```\n\nPercentage used on wider screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+                  "markdownDescription": "```yaml\nimages:\n  maxAvailableHeightPercent:\n    desktop: 74\n```\n\nPercentage used on wider screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
                 },
                 "mobile": {
                   "type": "number",
                   "exclusiveMinimum": 0,
                   "maximum": 100,
                   "description": "Percentage used on narrow screens.",
-                  "markdownDescription": "```yaml\nimages:\n  maxAvailableHeightPercent:\n    mobile: 68\n```\n\nPercentage used on narrow screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+                  "markdownDescription": "```yaml\nimages:\n  maxAvailableHeightPercent:\n    mobile: 68\n```\n\nPercentage used on narrow screens.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
                 }
               },
               "required": [
@@ -141,12 +166,12 @@
               "additionalProperties": false
             }
           ],
-          "markdownDescription": "```yaml\nimages:\n  maxAvailableHeightPercent:\n    desktop: 74\n    mobile: 68\n```\n\nMaximum percentage of viewport height used by managed images.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+          "markdownDescription": "```yaml\nimages:\n  maxAvailableHeightPercent:\n    desktop: 74\n    mobile: 68\n```\n\nMaximum percentage of viewport height used by centered-fit images. This setting is unavailable with prose-aligned presentation.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
         }
       },
       "additionalProperties": false,
-      "description": "Optional defaults for managed image presentation.",
-      "markdownDescription": "```yaml\nimages:\n  width: 900px\n```\n\nAdjusts managed-image sizing for pages below this directory.\n\n[Image sizing reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#image-sizing)"
+      "description": "Optional defaults for placing managed images inside the page content area. Persistent navigation remains outside this area.",
+      "markdownDescription": "```yaml\nimages:\n  presentation: prose-aligned\n  width: 900px\n```\n\nAdjusts managed-image presentation and sizing inside the content area for pages below this directory. Persistent navigation remains outside this area.\n\n[Image sizing reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#image-sizing)"
     },
     "sections": {
       "type": "object",
@@ -158,20 +183,23 @@
             {
               "const": "uniform",
               "title": "Uniform",
-              "description": "Use the normal page background for every H2 section. Tree navigation requires this pattern."
+              "description": "Use the normal page background for every H2 section. Tree navigation requires this pattern.",
+              "markdownDescription": "Use the normal page background for every H2 section. Tree navigation requires this pattern.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             },
             {
               "const": "alternating",
               "title": "Alternating",
-              "description": "Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation."
+              "description": "Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation.",
+              "markdownDescription": "Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             },
             {
               "const": "accented",
               "title": "Accented",
-              "description": "Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation."
+              "description": "Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation.",
+              "markdownDescription": "Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
             }
           ],
-          "markdownDescription": "```yaml\nsections:\n  backgroundPattern: alternating\n```\n\nSection background sequence inherited by descendant pages. Non-uniform patterns are invalid with tree navigation.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#page-themes)",
+          "markdownDescription": "```yaml\nsections:\n  backgroundPattern: alternating\n```\n\nSection background sequence inherited by descendant pages. Non-uniform patterns are invalid with tree navigation.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)",
           "examples": [
             "uniform",
             "alternating",
@@ -181,12 +209,12 @@
       },
       "additionalProperties": false,
       "description": "Page-local section presentation inherited by descendant pages.",
-      "markdownDescription": "```yaml\nsections:\n  backgroundPattern: alternating\n```\n\nAdjusts the H2 section background pattern for pages below this directory. Alternating and accented create full-width bands but are invalid when navigation resolves to tree.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#page-themes)"
+      "markdownDescription": "```yaml\nsections:\n  backgroundPattern: alternating\n```\n\nAdjusts the H2 section background pattern for pages below this directory. Alternating and accented create full-width bands but are invalid when navigation resolves to tree.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
     }
   },
   "additionalProperties": false,
   "description": "Limited page presentation overrides inherited by descendant pages. Site colors, corners, typography, content-block defaults and navigation remain global.",
   "$id": "https://janga.github.io/norna/schemas/page-theme.schema.json",
   "title": "Norna page theme",
-  "markdownDescription": "```yaml\nlayout:\n  textWidth: narrow\n  contentSpacing: compact\n```\n\nA limited theme in a page or category directory may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Tree navigation requires a uniform section background. Site colors, corners, typography, content-block defaults and navigation stay consistent.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.22/docs/theme.md#page-themes)"
+  "markdownDescription": "```yaml\nlayout:\n  textWidth: narrow\n  contentSpacing: compact\n```\n\nA limited theme in a page or category directory may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Tree navigation requires a uniform section background. Site colors, corners, typography, content-block defaults and navigation stay consistent.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.23/docs/theme.md#page-themes)"
 }