@janga/norna 0.7.27 → 0.7.29

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,51 @@ 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/
+        `-- guide/
+            |-- content.md
+            |-- tree-theme.yaml   # Optional inherited branch overrides
+            |-- images/
+            `-- pages/
+                `-- 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](https://janga.github.io/norna/reference/site/pages/#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 page 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).
+- Page directories use their URL slug. Set optional `navigation.order` in each
+  page’s frontmatter to order siblings; reordering keeps their paths unchanged.
+  New sites declare `sourceFormat: 2` in `site-config/settings.yaml`.
+- 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.
+- `public/` holds supported technical files and named site artwork (logo, icons and sharing image). Content images and documents belong in each page's `images/` and `downloads/`.
 
 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?
 
@@ -152,7 +164,7 @@ 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/pages/032-reference/` and
+The user reference is authored once under `site/root/pages/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.

package/astro.config.mjs

@@ -1,3 +1,6 @@
+import { compiledOutputDirectory } from './scripts/lib/publication-paths.mjs';
+import { devServerIdentityPlugin } from './scripts/lib/dev-server-identity.mjs';
+import { rewriteAttachmentLinks } from './scripts/lib/attachment-render.mjs';
 // @ts-check
 import { execFile } from 'node:child_process';
 import path from 'node:path';
@@ -16,7 +19,11 @@ import {
 	astroPublicDir,
 	engineRoot,
 	generatedImagesManifestPath,
+	siteDir,
+	sitePublicDir,
+	siteConfigPath,
 	siteContentPath,
+	siteHomePageDir,
 	siteImagesDir,
 	siteProjectRoot,
 	sitePagesDir,
@@ -72,7 +79,12 @@ const nornaGeneratedImagesWatcher = () => ({
 		const manifestPath = path.resolve(generatedImagesManifestPath);
 		const watchedSourcePaths = [
 			siteContentPath,
+			sitePublicDir,
+			siteConfigPath,
+			path.join(siteHomePageDir, 'tree-theme.yaml'),
+			path.join(siteHomePageDir, 'page-theme.yaml'),
 			siteImagesDir,
+			path.join(siteHomePageDir, 'downloads'),
 			sitePagesDir,
 		].map((watchedPath) => path.resolve(watchedPath));
 		let refreshTimer;
@@ -92,6 +104,7 @@ const nornaGeneratedImagesWatcher = () => ({
 				.then(async () => {
 					try {
 						await runGenerateImages();
+						await execFileAsync(process.execPath, [path.join(engineRoot, 'scripts', 'sync-site-public.mjs')], { cwd: siteProjectRoot });
 					} catch (error) {
 						const message = error instanceof Error ? error.message : String(error);
 						server.config.logger.error(`Norna image refresh failed:\n${message}`);
@@ -109,7 +122,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(() => {
@@ -150,7 +163,8 @@ markdownProcessor.createRenderer = async (shared) => {
 	const renderer = await createMarkdownRenderer(shared);
 	return {
 		...renderer,
-		render(source, options) {
+		async render(source, options) {
+			source = await rewriteAttachmentLinks(source, options?.fileURL, siteDir);
 			return renderer.render(prepareContentTabs(source, {
 				label: options?.fileURL?.pathname ?? 'Markdown',
 			}), options);
@@ -161,7 +175,23 @@ markdownProcessor.createRenderer = async (shared) => {
 // https://astro.build/config
 export default defineConfig({
 	base: projectConfig.site.basePath,
+	build: { assets: compiledOutputDirectory },
 	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],
@@ -175,6 +205,6 @@ export default defineConfig({
 		server: {
 			strictPort: true,
 		},
-		plugins: [nornaBasePathRedirect(), nornaGeneratedImagesWatcher()],
+		plugins: [nornaBasePathRedirect(), devServerIdentityPlugin(siteDir), nornaGeneratedImagesWatcher()],
 	},
 });

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
@@ -24,13 +24,13 @@ Commands:
   typography profiles    Show built-in typography profile values
   typography show        Show resolved typography for the selected site
   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 navigation group without an authored page body
   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.27",
+  "version": "0.7.29",
   "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,19 +101,20 @@
     "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:page-model": "node scripts/test-page-model.mjs && node --test scripts/test-page-order.mjs scripts/test-page-order-integration.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",
+    "test:site-links": "node scripts/test-site-link-graph.mjs && node --test scripts/test-page-attachments.mjs",
     "test:page-aliases": "node scripts/test-page-aliases.mjs",
     "test:sitemap": "node scripts/test-sitemap.mjs",
     "test:not-found-page": "node scripts/test-not-found-page.mjs",
     "test:site-node-commands": "node scripts/test-site-node-commands.mjs",
-    "test:page-move": "node scripts/test-page-move.mjs",
+    "test: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",
@@ -127,14 +129,16 @@
     "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:managed-media": "node scripts/test-managed-media.mjs && node scripts/test-markdown-images.mjs",
+    "test:markdown-images:browser": "node scripts/test-navigation.mjs --site-dir fixtures/markdown-images/site tests/markdown-images.spec.ts",
     "test:content-sync": "node scripts/test-content-sync.mjs",
-    "test:markdown-constructs": "node scripts/test-markdown-constructs.mjs",
+    "test:markdown-constructs": "node scripts/test-markdown-constructs.mjs && node scripts/test-standard-markdown-compatibility.mjs",
     "test:theme-presets": "node scripts/test-theme-presets.mjs",
     "test:presentation-contract": "node scripts/test-presentation-contract.mjs",
     "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",
@@ -147,13 +151,14 @@
     "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:site-public": "node scripts/test-site-public.mjs && node --test scripts/test-publication-paths.mjs",
     "test:cli-discovery": "node scripts/test-cli-discovery.mjs",
-    "test:dev-local": "node scripts/test-dev-local.mjs",
+    "test:dev-local": "node scripts/test-dev-local.mjs && npm run test:editor-preview",
+    "test:editor-preview": "node --test scripts/test-editor-site-preview.mjs && node --test editors/vscode/test/site-preview-actions-contract.mjs",
     "test:review-environments": "node scripts/test-review-environments.mjs",
     "test:review-environments:browser": "node scripts/test-review-environments-browser.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-language": "node scripts/test-editor-language-service.mjs && node --test scripts/test-editor-resource-actions.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",
@@ -173,7 +178,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 +193,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",