@janga/norna 0.7.25 → 0.7.27

package/README.md

@@ -71,8 +71,9 @@ site/
   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.
+- 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
   footer content.
@@ -133,24 +134,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/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

@@ -4,9 +4,11 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { defineConfig } from 'astro/config';
 import { satteri } from '@astrojs/markdown-satteri';
+import { prepareContentTabs } from './scripts/lib/content-tabs.mjs';
 import { getBasePathRedirectLocation } from './scripts/lib/base-path-redirect.mjs';
 import { nornaCodeFenceTransformer } from './scripts/lib/code-fence-metadata.mjs';
 import { nornaMarkdownRenderPlugin } from './scripts/lib/norna-markdown-render-plugin.mjs';
+import { nornaNotesRenderPlugin } from './scripts/lib/markdown-notes-render-plugin.mjs';
 import { nornaTableRenderPlugin } from './scripts/lib/table-render-plugin.mjs';
 import {
 	astroCacheDir,
@@ -133,6 +135,29 @@ const nornaGeneratedImagesWatcher = () => ({
 	},
 });
 
+const markdownProcessor = satteri({
+	features: {
+		gfm: { footnotes: {
+			label: projectConfig.locale.labels.footnotes,
+			backLabel: projectConfig.locale.labels.footnoteBackReference,
+		} },
+	},
+	mdastPlugins: [nornaNotesRenderPlugin, nornaMarkdownRenderPlugin],
+	hastPlugins: [nornaTableRenderPlugin],
+});
+const createMarkdownRenderer = markdownProcessor.createRenderer.bind(markdownProcessor);
+markdownProcessor.createRenderer = async (shared) => {
+	const renderer = await createMarkdownRenderer(shared);
+	return {
+		...renderer,
+		render(source, options) {
+			return renderer.render(prepareContentTabs(source, {
+				label: options?.fileURL?.pathname ?? 'Markdown',
+			}), options);
+		},
+	};
+};
+
 // https://astro.build/config
 export default defineConfig({
 	base: projectConfig.site.basePath,
@@ -141,18 +166,7 @@ export default defineConfig({
 		shikiConfig: {
 			transformers: [nornaCodeFenceTransformer],
 		},
-		processor: satteri({
-			features: {
-				gfm: {
-					footnotes: {
-						label: projectConfig.locale.labels.footnotes,
-						backLabel: projectConfig.locale.labels.footnoteBackReference,
-					},
-				},
-			},
-			mdastPlugins: [nornaMarkdownRenderPlugin],
-			hastPlugins: [nornaTableRenderPlugin],
-		}),
+		processor: markdownProcessor,
 	},
 	outDir: astroDistDir,
 	publicDir: astroPublicDir,

package/bin/norna-cli.mjs

@@ -23,14 +23,15 @@ 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/
   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
+  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
   deploy                 Build and deploy committed branch
@@ -100,6 +101,17 @@ if (command === '-h' || command === '--help' || command === 'help') {
 	process.exit(0);
 }
 
+if (command === 'migrate:check') {
+	try {
+		process.argv = [process.argv[0], process.argv[1], ...rest];
+		await import('../scripts/migrate-check.mjs');
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	}
+	process.exit(0);
+}
+
 const [
 	{ runAstroInherit },
 	{ engineRoot, siteProjectRoot },

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.25",
+  "version": "0.7.27",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -44,6 +44,7 @@
     "scripts/generate-schemas.mjs",
     "scripts/generate-search-index.mjs",
     "scripts/init-site.mjs",
+    "scripts/migrate-check.mjs",
     "scripts/lib/",
     "!scripts/lib/documentation-preset-candidates.mjs",
     "!scripts/lib/example-sites.mjs",
@@ -99,11 +100,13 @@
     "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-links && npm run test:page-aliases && npm run test:sitemap && npm run test:not-found-page && npm run test:site-node-commands && npm run test:page-move && npm run test:navigation-review && npm run test:nested-pages && npm run test:heading-ids && npm run test:navigation-model && npm run test:project-config && npm run test:edit-source-link && npm run test:static-search && npm run test:editor-language && npm run test:content-check && npm run test:content-sync-plan && npm run test:content-model && npm run test:theme-presets && npm run test:presentation-contract && npm run test: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: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: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: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-markdown": "node scripts/test-page-markdown.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:page-aliases": "node scripts/test-page-aliases.mjs",
     "test:sitemap": "node scripts/test-sitemap.mjs",
@@ -111,13 +114,15 @@
     "test:site-node-commands": "node scripts/test-site-node-commands.mjs",
     "test:page-move": "node scripts/test-page-move.mjs",
     "test:navigation-review": "node scripts/test-navigation-review.mjs",
-    "test:nested-pages": "node scripts/test-nested-pages.mjs",
+    "test:nested-pages": "node scripts/test-nested-pages.mjs && node scripts/test-top-navigation-contract.mjs",
     "test:heading-ids": "node scripts/test-heading-ids.mjs",
     "test:navigation-model": "node scripts/test-navigation-model.mjs",
     "test:schemas": "node scripts/test-schemas.mjs",
     "test:project-config": "node scripts/test-project-config.mjs",
+    "test:locales": "node scripts/test-locales.mjs",
     "test:edit-source-link": "node scripts/test-edit-source-link.mjs",
     "test:static-search": "node scripts/test-static-search.mjs",
+    "test:search:browser": "node scripts/test-navigation.mjs --site-dir site tests/search-navigation.spec.ts",
     "test:content-check": "node scripts/test-content-check.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",
@@ -130,6 +135,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: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",
     "test:navigation-surfaces:top": "node scripts/test-navigation.mjs --site-dir fixtures/content-model-v2/site tests/navigation-surfaces-top.spec.ts",
@@ -161,6 +167,7 @@
     "test:navigation:stress": "node scripts/test-navigation.mjs tests/navigation-stress.spec.ts",
     "test:navigation:preview": "node scripts/test-navigation-preview.mjs",
     "package:check": "node scripts/test-package-check.mjs",
+    "test:migration-check": "node scripts/test-migration-check.mjs",
     "release:publish": "npm publish --access public --registry=https://registry.npmjs.org/ --cache /private/tmp/norna-npm-cache",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
@@ -175,7 +182,9 @@
     "embla-carousel": "^8.6.0",
     "js-yaml": "^4.3.1",
     "pagefind": "1.5.2",
-    "satteri": "^0.9.1"
+    "parse5": "7.3.0",
+    "satteri": "^0.9.1",
+    "yaml": "2.9.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.61.1",

package/schemas/card-list.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "Show related choices as cards with optional images and links. Set link to make the whole card clickable.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "items"
+  ],
+  "properties": {
+    "layout": {
+      "type": "string",
+      "description": "Place each card image above, left, or right of its text. Defaults to image-top.",
+      "default": "image-top",
+      "enum": [
+        "image-top",
+        "image-left",
+        "image-right"
+      ],
+      "minLength": 1,
+      "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+    },
+    "flow": {
+      "type": "string",
+      "description": "Arrange cards as a responsive grid or a vertical stack. Defaults to grid.",
+      "default": "grid",
+      "enum": [
+        "grid",
+        "stack"
+      ],
+      "minLength": 1,
+      "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+    },
+    "size": {
+      "type": "string",
+      "description": "Set the coordinated card and image size. Defaults to m.",
+      "default": "m",
+      "enum": [
+        "s",
+        "m",
+        "l",
+        "xl"
+      ],
+      "minLength": 1,
+      "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+    },
+    "width": {
+      "type": "string",
+      "description": "Override the root theme's maximum width for this card list.",
+      "enum": [
+        "text",
+        "narrow",
+        "normal",
+        "wide"
+      ],
+      "minLength": 1,
+      "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+    },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "title"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Start another card. Every card requires a title.",
+            "minLength": 1,
+            "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+          },
+          "text": {
+            "type": "string",
+            "description": "Optional card text.",
+            "minLength": 1,
+            "pattern": "^(?=[\\s\\S]*\\S)[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F-\\x9F]*$(?![\\s\\S])"
+          },
+          "image": {
+            "type": "string",
+            "description": "Optional managed image filename.",
+            "minLength": 1,
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])"
+          },
+          "link": {
+            "type": "string",
+            "description": "Optional URL opened when the card is activated.",
+            "minLength": 1,
+            "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+          },
+          "badge-text": {
+            "type": "string",
+            "description": "Optional short badge displayed on the card.",
+            "minLength": 1,
+            "pattern": "^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])"
+          }
+        },
+        "anyOf": [
+          {
+            "required": [
+              "text"
+            ]
+          },
+          {
+            "required": [
+              "image"
+            ]
+          },
+          {
+            "required": [
+              "link"
+            ]
+          }
+        ]
+      }
+    }
+  },
+  "$id": "https://janga.github.io/norna/schemas/card-list.schema.json",
+  "title": "Norna card-list"
+}

package/schemas/category.schema.json

@@ -5,16 +5,16 @@
     "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.25/docs/pages.md#navigation-categories)"
+      "description": "Navigation label for a group of child pages without an authored page body.",
+      "markdownDescription": "```yaml\nlabel: Guides\n```\n\nThe category label shown in global navigation, tree navigation, mobile navigation, and breadcrumbs.\n\n[Navigation category reference (current)](https://janga.github.io/norna/reference/site/pages/#page-or-category)\n\n[Norna 0.7.27 source reference](https://github.com/janga/norna/blob/v0.7.27/site/pages/032-reference/pages/010-site/pages/020-pages/content.md#page-or-category)"
     }
   },
   "required": [
     "label"
   ],
   "additionalProperties": false,
-  "description": "A non-routable navigation category containing child pages.",
+  "description": "A navigation group without an authored page body. Opening its URL redirects when its first listed direct child is a page; otherwise it shows a generated child list.",
   "$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.25/docs/pages.md#navigation-categories)"
+  "markdownDescription": "```yaml\nlabel: Guides\n```\n\n`category.yaml` groups child pages without editorial content. Its URL opens the first listed direct page, or a generated child list when the first child is a category.\n\n[Navigation category reference (current)](https://janga.github.io/norna/reference/site/pages/#page-or-category)\n\n[Norna 0.7.27 source reference](https://github.com/janga/norna/blob/v0.7.27/site/pages/032-reference/pages/010-site/pages/020-pages/content.md#page-or-category)"
 }