@janga/norna 0.7.26 → 0.7.28

package/README.md

@@ -20,7 +20,7 @@ implementing a new presentation layer for every project.
 [![A multi-page dog shelter site with a logo, navigation between pages, text, a card, and a managed image.](docs/assets/norna-dog-shelter.jpg)](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/)
 
 The screenshot shows the built
-[multi-page example source](examples/complete-sites/dog-shelter-multi-page/).
+[multi-page example source](examples/complete-sites/dog-shelter-multi-page).
 
 ## Quick Start
 
@@ -50,39 +50,48 @@ locally installed and pinned Norna version.
 
 ```text
 site/
-|-- config.yaml
-|-- theme.yaml
-|-- sitewide-content.yaml
-|-- pages/
-|   |-- 000-home/
-|   |   |-- content.md
-|   |   `-- images/
-|   `-- 010-guides/
-|       |-- category.yaml
-|       `-- pages/
-|           `-- 010-installation/
-|               |-- content.md
-|               `-- images/
-`-- public/
+|-- site-config/
+|   |-- settings.yaml
+|   `-- shared-content.yaml
+|-- public/
+`-- root/
+    |-- content.md       # Required homepage
+    |-- tree-theme.yaml  # Required preset and inherited overrides
+    |-- page-theme.yaml  # Optional homepage-only overrides
+    |-- images/
+    `-- pages/
+        `-- 010-guide/
+            |-- content.md
+            |-- tree-theme.yaml   # Optional inherited branch overrides
+            |-- images/
+            `-- pages/
+                `-- 010-install/content.md
 ```
 
-- `pages/000-home/content.md` is the required homepage at `/`.
-- 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. Opening a category URL leads to its first
-  listed direct page or a generated child list; see
-  [Category destinations](docs/pages.md#opening-a-category-url).
-- `theme.yaml` normally selects one complete visual preset.
-- `sitewide-content.yaml` holds shared logo display settings, banners, and
+- `root/content.md` is the required homepage at `/`; `root/pages/` contains its
+  children. The site container holds shared configuration and public files
+  beside this root page. `root/` never becomes a URL segment.
+- Every ordered directory under `pages/` contains `content.md` for a routable
+  page. A parent can append a generated list of its direct child pages with
+  `page.listChildren: true`; see
+  [Child-page lists](https://janga.github.io/norna/reference/site/pages/#list-child-pages).
+- A page may contain local images, visual settings and nested
+  entries under its own `pages/` directory.
+- `root/tree-theme.yaml` selects shared visual defaults. Optional `page-theme.yaml`
+  overrides its page alone; a child's `tree-theme.yaml` is inherited further.
+  The root requires `preset`; elsewhere it is optional and explicitly replaces
+  the inherited base. Without it, only supplied fields change.
+- `site-config/shared-content.yaml` holds shared logo display settings, banners, and
   footer content.
-- `config.yaml` holds the public URL and optional language, local and remote
+- `site-config/settings.yaml` holds the public URL and optional language, local and remote
   source links, navigation model, static search, and scroll behavior.
 - `public/` holds static files copied without processing.
 
 Norna validates this structure, processes managed images when needed, and
-builds the generated website into `dist/`.
+builds the generated website into `dist/`. Sites using an earlier layout need
+manual [source conversion](https://janga.github.io/norna/reference/site/files/#convert-the-former-homepage-folder).
+`norna site:upgrade` checks the layout and reports former locations without
+moving or overwriting source files.
 
 ## Why Norna?
 
@@ -134,24 +143,31 @@ components, and rendering logic.
 
 GitHub CLI and Playwright are needed only for specific deploy helpers and
 engine diagnostics, not for ordinary editing and local preview. See
-[Requirements and limitations](docs/requirements.md) for the exact boundaries.
+[Requirements and limitations](https://janga.github.io/norna/reference/site/requirements/) for the exact boundaries.
 
 ## Documentation
 
 - [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)
-- [Explanation and JavaScript boundaries](docs/README.md#explanation)
-- [Command and platform reference](docs/README.md#command-and-platform-reference)
-- [Troubleshooting](docs/README.md#troubleshooting)
+- [Site files](https://janga.github.io/norna/reference/site/files/)
+- [Upgrading an existing site](https://janga.github.io/norna/reference/workflows/upgrading/)
+- [Complete reference](https://janga.github.io/norna/reference/)
+- [Working on a site](https://janga.github.io/norna/reference/workflows/)
+- [JavaScript and accessibility](https://janga.github.io/norna/reference/reader/accessibility/)
+- [Commands](https://janga.github.io/norna/reference/commands/invocation/)
+- [Troubleshooting](https://janga.github.io/norna/faq/installation/)
 - [AI-readable documentation index](https://janga.github.io/norna/llms.txt)
 
 Engine contributors should start with
 [Engine Development](docs/engine-development.md). Planning and future work are
 tracked in [BACKLOG.md](BACKLOG.md).
 
+The user reference is authored once under `site/root/pages/032-reference/` and
+rendered on the documentation site. It describes current development; use the
+installed release's Git tag when checking older behavior. Tags through 0.7.26
+keep their reference under `docs/`; later tags use the documentation page tree.
+The [contributor documentation](docs/README.md) explains maintenance and version
+selection.
+
 ## Support And License
 
 Use the [issue tracker](https://github.com/janga/norna/issues) for reproducible

package/astro.config.mjs

@@ -17,6 +17,7 @@ import {
 	engineRoot,
 	generatedImagesManifestPath,
 	siteContentPath,
+	siteHomePageDir,
 	siteImagesDir,
 	siteProjectRoot,
 	sitePagesDir,
@@ -72,6 +73,8 @@ const nornaGeneratedImagesWatcher = () => ({
 		const manifestPath = path.resolve(generatedImagesManifestPath);
 		const watchedSourcePaths = [
 			siteContentPath,
+			path.join(siteHomePageDir, 'tree-theme.yaml'),
+			path.join(siteHomePageDir, 'page-theme.yaml'),
 			siteImagesDir,
 			sitePagesDir,
 		].map((watchedPath) => path.resolve(watchedPath));
@@ -109,7 +112,7 @@ const nornaGeneratedImagesWatcher = () => ({
 		const scheduleStructureReload = (changedPath) => {
 			if (!isRelevantSourcePath(changedPath)) return;
 			const filename = path.basename(changedPath);
-			if (filename !== 'category.yaml' && filename !== 'theme.yaml') return;
+			if (!['tree-theme.yaml', 'page-theme.yaml'].includes(filename)) return;
 
 			clearTimeout(structureReloadTimer);
 			structureReloadTimer = setTimeout(() => {
@@ -162,6 +165,21 @@ markdownProcessor.createRenderer = async (shared) => {
 export default defineConfig({
 	base: projectConfig.site.basePath,
 	cacheDir: astroCacheDir,
+	prefetch: { prefetchAll: false, defaultStrategy: 'hover' },
+	integrations: [{
+		name: 'norna-navigation-continuity',
+		hooks: {
+			'astro:config:setup': ({ injectScript }) => {
+				injectScript('page', `
+					import { prefetch } from 'astro:prefetch';
+					import { setupNavigationContinuity } from ${JSON.stringify(path.join(engineRoot, 'src/lib/navigationContinuity.ts'))};
+					if (document.documentElement.hasAttribute('data-navigation-continuity')) {
+						setupNavigationContinuity(prefetch);
+					}
+				`);
+			},
+		},
+	}],
 	markdown: {
 		shikiConfig: {
 			transformers: [nornaCodeFenceTransformer],

package/bin/norna-cli.mjs

@@ -15,7 +15,7 @@ Commands:
   dev:logs               Show local dev server logs
   dev:stop               Stop local dev server
   check                  Validate configuration and content
-  config:check           Validate site/config.yaml
+  config:check           Validate site/site-config/settings.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
@@ -23,14 +23,14 @@ Commands:
   theme:export           Export a commented theme preset reference
   typography profiles    Show built-in typography profile values
   typography show        Show resolved typography for the selected site
-  site:public            Sync site/public/ to public/
+  site:public            Sync static files to the selected site's .norna/public/
+  site:upgrade           Convert former configuration and homepage locations
   images                 Generate optimized image variants
   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
   page:move              Move a page subtree and update internal links
-  category:add           Add a non-routable category to the site page tree
   migrate:check          Audit a Docusaurus project without modifying it
   build                  Build the selected site
   build:local            Build and restart local dev server
@@ -169,6 +169,8 @@ try {
 		throw new Error(`Unknown typography command: ${subcommand ?? ''}\n${usage}`);
 	} else if (command === 'site:public') {
 		await runScript('scripts/sync-site-public.mjs', rest);
+	} else if (command === 'site:upgrade') {
+		await runScript('scripts/upgrade-site.mjs', rest);
 	} else if (command === 'images') {
 		await runScript('scripts/generate-images.mjs', rest);
 	} else if (command === 'engine:update') {
@@ -182,7 +184,7 @@ try {
 	} 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]);
+		throw new Error('category:add is no longer supported. Use page:add, then set page.listChildren: true in its content.md to list direct children.');
 	} 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.26",
+  "version": "0.7.28",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -56,6 +56,7 @@
     "scripts/sync-content-sections.mjs",
     "scripts/sync-site-public.mjs",
     "scripts/update-engine.mjs",
+    "scripts/upgrade-site.mjs",
     "scripts/watch-pages-deploy.mjs",
     "README.md"
   ],
@@ -100,11 +101,12 @@
     "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:migration-check && 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:locales && 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:presentation-review && 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:review-environments && 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:table-sorting && 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:site-upgrade && npm run test:page-markdown && npm run test:migration-check && 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:locales && 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-inheritance && npm run test:theme-presets && npm run test:presentation-contract && npm run test:presentation-review && 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:review-environments && 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:browser-test-server && npm run test:table-sorting && 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:examples:browser": "node scripts/test-navigation.mjs --site-dir site tests/examples-gallery.spec.ts",
     "test:page-model": "node scripts/test-page-model.mjs",
+    "test:site-upgrade": "node scripts/test-site-upgrade.mjs",
     "test:page-markdown": "node scripts/test-page-markdown.mjs && node scripts/test-structured-blocks.mjs && node scripts/test-named-notes.mjs && node scripts/test-content-tabs.mjs",
     "test:tabs:browser": "node scripts/test-navigation.mjs --site-dir fixtures/content-tabs/site tests/content-tabs.spec.ts",
     "test:site-links": "node scripts/test-site-link-graph.mjs",
@@ -112,7 +114,7 @@
     "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:page-move": "node scripts/test-page-move.mjs && node --test scripts/test-editor-page-placement.mjs",
     "test:navigation-review": "node scripts/test-navigation-review.mjs",
     "test:nested-pages": "node scripts/test-nested-pages.mjs && node scripts/test-top-navigation-contract.mjs",
     "test:heading-ids": "node scripts/test-heading-ids.mjs",
@@ -135,6 +137,7 @@
     "test:presentation-review": "node scripts/test-presentation-review-fixture.mjs",
     "test:presentation:browser": "node scripts/test-navigation.mjs --site-dir fixtures/preset-baseline/site tests/presentation-contract.spec.ts",
     "test:table-layout:top": "node scripts/test-navigation.mjs --site-dir fixtures/top-navigation/site tests/table-width-top.spec.ts",
+    "test:browser-test-server": "node scripts/test-browser-test-server.mjs",
     "test:table-sorting": "node scripts/test-navigation.mjs --site-dir fixtures/table-sorting/site tests/table-sorting.spec.ts",
     "test:table-context:browser": "node scripts/test-navigation.mjs --site-dir fixtures/presentation-review/site tests/table-responsive-context.spec.ts",
     "test:navigation-surfaces:browser": "npm run test:navigation-surfaces:top && npm run test:navigation-surfaces:tree",
@@ -173,7 +176,8 @@
     "release:minor": "node scripts/release.mjs minor",
     "release:major": "node scripts/release.mjs major",
     "preview": "node bin/norna.mjs preview",
-    "astro": "node bin/norna.mjs astro"
+    "astro": "node bin/norna.mjs astro",
+    "test:theme-inheritance": "node scripts/test-theme-inheritance.mjs"
   },
   "dependencies": {
     "@astrojs/markdown-satteri": "0.3.4",
@@ -187,7 +191,7 @@
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.61.1",
+    "@playwright/test": "^1.63.0",
     "knip": "6.33.0"
   }
 }

package/schemas/card-list.schema.json

@@ -45,7 +45,7 @@
     },
     "width": {
       "type": "string",
-      "description": "Override the root theme's maximum width for this card list.",
+      "description": "Override the shared theme's maximum width for this card list.",
       "enum": [
         "text",
         "narrow",