@janga/norna 0.7.18 → 0.7.22

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,6 +135,11 @@ 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'),

package/bin/norna-cli.mjs

@@ -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.22",
   "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,11 +87,13 @@
     "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-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: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-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",
@@ -82,6 +102,15 @@
     "test:content-check": "node scripts/test-content-check.mjs",
     "test:content-model-v2": "node scripts/test-content-model-v2.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: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:engine-commands": "node scripts/test-engine-commands.mjs",
@@ -90,6 +119,7 @@
     "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 +133,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.22/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.22/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.22/docs/configuration.md#url)",
       "examples": [
         "https://example.com/",
         "https://owner.github.io/repository-name/"
@@ -41,7 +41,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.22/docs/configuration.md#language)"
     },
     "navigation": {
       "type": "object",
@@ -71,18 +71,28 @@
               "description": "Use a hierarchical site-wide navigation tree."
             }
           ],
-          "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.22/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.18/docs/pages.md#navigation)"
+      "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)"
     },
     "scrollBehavior": {
       "default": "instant",
@@ -100,7 +110,7 @@
           "description": "Use the browser's native smooth scrolling for anchor navigation."
         }
       ],
-      "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.22/docs/configuration.md#scrollbehavior)",
       "examples": [
         "instant",
         "smooth"
@@ -114,5 +124,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.22/docs/configuration.md)"
 }

package/schemas/content-frontmatter.schema.json

@@ -9,7 +9,7 @@
           "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.22/docs/content.md#page-title-and-frontmatter)",
           "examples": [
             "About this project."
           ]
@@ -17,7 +17,7 @@
       },
       "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```\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)"
     },
     "navigation": {
       "description": "Optional navigation metadata for this page.",
@@ -27,7 +27,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.22/docs/pages.md#navigation)",
           "examples": [
             true,
             false
@@ -35,12 +35,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.22/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.22/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",

package/schemas/page-theme.schema.json

@@ -25,7 +25,7 @@
               "description": "Use more expansive spacing between sections and structured blocks."
             }
           ],
-          "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.18/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)",
           "examples": [
             "compact",
             "normal",
@@ -52,7 +52,7 @@
               "description": "Allow body text to use more horizontal space."
             }
           ],
-          "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.18/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)",
           "examples": [
             "narrow",
             "normal",
@@ -62,7 +62,7 @@
       },
       "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 this page and its descendants.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.18/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.22/docs/theme.md#page-themes)"
     },
     "images": {
       "type": "object",
@@ -71,7 +71,7 @@
           "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.18/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.22/docs/theme.md#image-sizing)"
         },
         "maxAvailableWidthPercent": {
           "description": "Maximum percentage of available horizontal space used by managed images.",
@@ -89,14 +89,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.18/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.22/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.18/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.22/docs/theme.md#image-sizing)"
                 }
               },
               "required": [
@@ -106,7 +106,7 @@
               "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.18/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.22/docs/theme.md#image-sizing)"
         },
         "maxAvailableHeightPercent": {
           "description": "Maximum percentage of viewport height used by managed images.",
@@ -124,14 +124,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.18/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.22/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.18/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.22/docs/theme.md#image-sizing)"
                 }
               },
               "required": [
@@ -141,52 +141,52 @@
               "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.18/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 managed images.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.22/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 this page and its descendants.\n\n[Image sizing reference](https://github.com/janga/norna/blob/v0.7.18/docs/theme.md#image-sizing)"
+      "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)"
     },
     "sections": {
       "type": "object",
       "properties": {
         "backgroundPattern": {
-          "description": "Section background sequence inherited by descendant pages.",
+          "description": "Section background sequence inherited by descendant pages. Non-uniform patterns are invalid with tree navigation.",
           "type": "string",
           "oneOf": [
             {
               "const": "uniform",
               "title": "Uniform",
-              "description": "Use the palette base surface for every section."
+              "description": "Use the normal page background for every H2 section. Tree navigation requires this pattern."
             },
             {
               "const": "alternating",
               "title": "Alternating",
-              "description": "Alternate between the palette base and soft surfaces."
+              "description": "Alternate normal and subtly contrasting full-width section backgrounds. Available with sections and top navigation."
             },
             {
-              "const": "cycling",
-              "title": "Cycling",
-              "description": "Cycle through the palette base, soft and emphasis surfaces."
+              "const": "accented",
+              "title": "Accented",
+              "description": "Move through base, soft, emphasis and soft full-width section backgrounds before repeating. Available with sections and top navigation."
             }
           ],
-          "markdownDescription": "```yaml\nsections:\n  backgroundPattern: alternating\n```\n\nSection background sequence inherited by descendant pages.\n\n[Read the relevant reference](https://github.com/janga/norna/blob/v0.7.18/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)",
           "examples": [
             "uniform",
             "alternating",
-            "cycling"
+            "accented"
           ]
         }
       },
       "additionalProperties": false,
       "description": "Page-local section presentation inherited by descendant pages.",
-      "markdownDescription": "```yaml\nsections:\n  backgroundPattern: alternating\n```\n\nAdjusts the section background sequence for this page and its descendants.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.18/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.22/docs/theme.md#page-themes)"
     }
   },
   "additionalProperties": false,
-  "description": "Limited page presentation overrides inherited by descendant pages. Site colors, shapes, typography and navigation remain global.",
+  "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 page theme may adjust only page layout, managed-image sizing and the section background pattern. Descendant pages inherit these values. Site colors, shapes and typography stay consistent.\n\n[Page theme reference](https://github.com/janga/norna/blob/v0.7.18/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.22/docs/theme.md#page-themes)"
 }