@janga/norna 0.7.26 → 0.7.27

package/scripts/add-site-node.mjs

@@ -246,6 +246,6 @@ console.log(`${action} ${kind} "${title}" at ${toDisplayPath(destination)}.`);
 if (kind === 'page') {
 	console.log(`URL: /${pagePath}/`);
 } else {
-	console.log('This navigation category has no page or URL of its own.');
+	console.log('This navigation category has no authored content page. Norna generates its destination from the child pages.');
 	console.log(`Child URL prefix: /${pagePath}/`);
 }

package/scripts/lib/documentation-links.mjs

@@ -1,8 +1,39 @@
 import packageJson from '../../package.json' with { type: 'json' };
+import routes from './documentation-routes.json' with { type: 'json' };
+
+const websiteRoot = 'https://janga.github.io/norna/reference/';
+const repositoryRoot = 'https://github.com/janga/norna/blob/';
+
+// Release tags through 0.7.26 contain the reference under docs/. Newer tags
+// contain its single authored source in the documentation site's page tree.
+export const usesLegacyReference = (version) => {
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version ?? '');
+	if (!match) return false;
+	const [major, minor, patch] = match.slice(1).map(Number);
+	return major === 0 && (minor < 7 || (minor === 7 && patch <= 26));
+};
+
+const referenceDestination = (file, anchor) => {
+	const target = routes.legacy[`${file}#${anchor}`] ?? routes.legacy[file];
+	if (!target) throw new Error(`Unknown documentation destination: ${file}${anchor ? `#${anchor}` : ''}`);
+	const [route, targetAnchor] = target.split('#');
+	const source = routes.sources[route];
+	if (!source) throw new Error(`Missing documentation source for ${route}`);
+	return { route, source, anchor: targetAnchor, url: websiteRoot + target };
+};
+
+export const documentationLinkForVersion = (version, label, file, anchor) => {
+	const destination = referenceDestination(file, anchor);
+	const reference = version ? `v${version}` : 'main';
+	const source = usesLegacyReference(version)
+		? `docs/${file}${anchor ? `#${anchor}` : ''}`
+		: `${destination.source}${destination.anchor ? `#${destination.anchor}` : ''}`;
+	const sourceLabel = version ? `Norna ${version} source reference` : 'Reference source';
+	return `[${label} (current)](${destination.url})\n\n[${sourceLabel}](${repositoryRoot}${reference}/${source})`;
+};
 
 export const documentationRef = `v${packageJson.version}`;
-export const documentationRoot = `https://github.com/janga/norna/blob/${documentationRef}/docs`;
 
 export const documentationLink = (label, file, anchor) => (
-	`[${label}](${documentationRoot}/${file}${anchor ? `#${anchor}` : ''})`
+	documentationLinkForVersion(packageJson.version, label, file, anchor)
 );

package/scripts/lib/documentation-routes.json

@@ -0,0 +1,222 @@
+{
+  "sources": {
+    "site/files/": "site/pages/032-reference/pages/010-site/pages/010-files/content.md",
+    "site/pages/": "site/pages/032-reference/pages/010-site/pages/020-pages/content.md",
+    "site/urls/": "site/pages/032-reference/pages/010-site/pages/030-urls/content.md",
+    "site/metadata/": "site/pages/032-reference/pages/010-site/pages/040-metadata/content.md",
+    "site/images/": "site/pages/032-reference/pages/010-site/pages/050-images/content.md",
+    "site/public-files/": "site/pages/032-reference/pages/010-site/pages/060-public-files/content.md",
+    "site/requirements/": "site/pages/032-reference/pages/010-site/pages/070-requirements/content.md",
+    "configuration/site/": "site/pages/032-reference/pages/020-configuration/pages/010-site/content.md",
+    "configuration/language/": "site/pages/032-reference/pages/020-configuration/pages/020-language/content.md",
+    "configuration/navigation/": "site/pages/032-reference/pages/020-configuration/pages/030-navigation/content.md",
+    "configuration/search/": "site/pages/032-reference/pages/020-configuration/pages/040-search/content.md",
+    "configuration/source-links/": "site/pages/032-reference/pages/020-configuration/pages/050-source-links/content.md",
+    "configuration/theme/": "site/pages/032-reference/pages/020-configuration/pages/060-theme/content.md",
+    "configuration/presets/": "site/pages/032-reference/pages/020-configuration/pages/065-presets/content.md",
+    "configuration/palettes/": "site/pages/032-reference/pages/020-configuration/pages/070-palettes/content.md",
+    "configuration/appearance/": "site/pages/032-reference/pages/020-configuration/pages/080-appearance/content.md",
+    "configuration/layout/": "site/pages/032-reference/pages/020-configuration/pages/090-layout/content.md",
+    "configuration/images/": "site/pages/032-reference/pages/020-configuration/pages/100-images/content.md",
+    "configuration/typography/": "site/pages/032-reference/pages/020-configuration/pages/110-typography/content.md",
+    "configuration/sections/": "site/pages/032-reference/pages/020-configuration/pages/120-sections/content.md",
+    "configuration/shared-content/": "site/pages/032-reference/pages/020-configuration/pages/130-shared-content/content.md",
+    "content/markdown/": "site/pages/032-reference/pages/030-content/pages/010-markdown/content.md",
+    "content/structured-blocks/": "site/pages/032-reference/pages/030-content/pages/015-structured-blocks/content.md",
+    "content/images/": "site/pages/032-reference/pages/030-content/pages/020-images/content.md",
+    "content/cards/": "site/pages/032-reference/pages/030-content/pages/030-cards/content.md",
+    "content/child-lists/": "site/pages/032-reference/pages/030-content/pages/040-child-lists/content.md",
+    "content/callouts/": "site/pages/032-reference/pages/030-content/pages/050-callouts/content.md",
+    "content/tabs/": "site/pages/032-reference/pages/030-content/pages/060-tabs/content.md",
+    "content/details/": "site/pages/032-reference/pages/030-content/pages/070-details/content.md",
+    "content/tables/": "site/pages/032-reference/pages/030-content/pages/080-tables/content.md",
+    "content/code/": "site/pages/032-reference/pages/030-content/pages/090-code/content.md",
+    "content/sidenotes/": "site/pages/032-reference/pages/030-content/pages/100-sidenotes/content.md",
+    "content/footnotes/": "site/pages/032-reference/pages/030-content/pages/110-footnotes/content.md",
+    "commands/invocation/": "site/pages/032-reference/pages/040-commands/pages/010-invocation/content.md",
+    "commands/init/": "site/pages/032-reference/pages/040-commands/pages/020-init/content.md",
+    "commands/create/": "site/pages/032-reference/pages/040-commands/pages/030-create/content.md",
+    "commands/move/": "site/pages/032-reference/pages/040-commands/pages/040-move/content.md",
+    "commands/validate/": "site/pages/032-reference/pages/040-commands/pages/050-validate/content.md",
+    "commands/navigation/": "site/pages/032-reference/pages/040-commands/pages/055-navigation/content.md",
+    "commands/development/": "site/pages/032-reference/pages/040-commands/pages/060-development/content.md",
+    "commands/build/": "site/pages/032-reference/pages/040-commands/pages/070-build/content.md",
+    "commands/publishing/": "site/pages/032-reference/pages/040-commands/pages/080-publishing/content.md",
+    "commands/theme/": "site/pages/032-reference/pages/040-commands/pages/090-theme/content.md",
+    "commands/engine/": "site/pages/032-reference/pages/040-commands/pages/100-engine/content.md",
+    "commands/migration-audit/": "site/pages/032-reference/pages/040-commands/pages/110-migration-audit/content.md",
+    "reader/display/": "site/pages/032-reference/pages/050-reader/pages/010-display/content.md",
+    "reader/accessibility/": "site/pages/032-reference/pages/050-reader/pages/020-accessibility/content.md",
+    "workflows/editor/": "site/pages/032-reference/pages/060-workflows/pages/010-editor/content.md",
+    "workflows/editor-ai-suggestions/": "site/pages/032-reference/pages/060-workflows/pages/015-editor-ai-suggestions/content.md",
+    "workflows/publishing/": "site/pages/032-reference/pages/060-workflows/pages/020-publishing/content.md",
+    "workflows/embedded-publishing/": "site/pages/032-reference/pages/060-workflows/pages/030-embedded-publishing/content.md",
+    "workflows/upgrading/": "site/pages/032-reference/pages/060-workflows/pages/040-upgrading/content.md",
+    "workflows/legacy-source/": "site/pages/032-reference/pages/060-workflows/pages/050-legacy-source/content.md"
+  },
+  "legacy": {
+    "site-files.md": "site/files/",
+    "pages.md": "site/pages/",
+    "configuration.md": "configuration/site/",
+    "content.md": "content/markdown/",
+    "theme.md": "configuration/theme/",
+    "typography.md": "configuration/typography/",
+    "images-and-metadata.md": "site/images/",
+    "public-files.md": "site/public-files/",
+    "sitewide-content.md": "configuration/shared-content/",
+    "commands.md": "commands/invocation/",
+    "local-development.md": "commands/development/",
+    "requirements.md": "site/requirements/",
+    "publishing.md": "workflows/publishing/",
+    "upgrading.md": "workflows/upgrading/",
+    "editor-support.md": "workflows/editor/",
+    "client-javascript.md": "reader/accessibility/",
+    "presentation-guarantees.md": "reader/accessibility/",
+    "site-files.md#root-files": "site/files/#source-layout",
+    "site-files.md#page-hierarchy": "site/files/#page-folders",
+    "site-files.md#public-files": "site/public-files/",
+    "site-files.md#selecting-the-site-directory": "commands/invocation/#site-selection",
+    "site-files.md#versioned-files": "site/files/#generated-files",
+    "site-files.md#generated-files": "site/files/#generated-files",
+    "pages.md#homepage-and-top-level-entries": "site/pages/#page-or-category",
+    "pages.md#choose-a-section-page-or-category": "site/pages/#page-or-category",
+    "pages.md#review-an-existing-hierarchy": "commands/navigation/",
+    "pages.md#navigation-categories": "site/pages/#page-or-category",
+    "pages.md#opening-a-category-url": "site/pages/#opening-a-category-url",
+    "pages.md#reachable-content-and-stable-links": "site/pages/#opening-a-category-url",
+    "pages.md#nested-pages": "site/pages/#page-or-category",
+    "pages.md#directory-names-order-and-urls": "site/pages/#names-and-order",
+    "pages.md#preserve-old-page-urls": "site/urls/#keep-an-old-url",
+    "pages.md#move-or-reconcile-a-page": "commands/move/",
+    "pages.md#create-pages-and-categories": "commands/create/",
+    "pages.md#page-content": "content/markdown/",
+    "pages.md#navigation": "configuration/navigation/",
+    "pages.md#focus-reading": "reader/display/#focus-reading",
+    "pages.md#current-reading-position": "configuration/navigation/#orientation-and-long-trees",
+    "pages.md#page-images": "site/images/",
+    "pages.md#page-themes": "configuration/theme/#page-themes",
+    "configuration.md#url": "configuration/site/#public-url",
+    "configuration.md#language": "configuration/language/",
+    "configuration.md#what-the-setting-changes": "configuration/language/",
+    "configuration.md#choose-a-language-tag": "configuration/language/",
+    "configuration.md#supported-languages": "configuration/language/",
+    "configuration.md#search-and-translation-boundaries": "configuration/language/",
+    "configuration.md#edit-link": "configuration/source-links/",
+    "configuration.md#local-editor": "configuration/source-links/#destination-rules",
+    "configuration.md#remote-source-host": "configuration/source-links/#fields",
+    "configuration.md#navigation": "configuration/navigation/",
+    "configuration.md#navigationmode": "configuration/navigation/",
+    "configuration.md#one-page-sections": "configuration/navigation/",
+    "configuration.md#top-level-pages-top": "configuration/navigation/",
+    "configuration.md#child-pages-or-categories-tree": "configuration/navigation/",
+    "configuration.md#search": "configuration/search/",
+    "configuration.md#scrollbehavior": "configuration/site/#anchor-movement",
+    "configuration.md#publishing-discovery": "commands/publishing/",
+    "configuration.md#site-directory-selection": "commands/invocation/#site-selection",
+    "content.md#page-title-and-frontmatter": "site/metadata/",
+    "content.md#sections": "content/markdown/#page-title-and-sections",
+    "content.md#internal-links": "site/urls/",
+    "content.md#norna-blocks": "content/structured-blocks/",
+    "content.md#child-page-list": "content/child-lists/",
+    "content.md#image-stack": "content/images/#image-stack",
+    "content.md#image-carousel": "content/images/#image-carousel",
+    "content.md#card-list": "content/cards/",
+    "content.md#image-files": "site/images/",
+    "content.md#markdown-images": "content/markdown/#markdown-images",
+    "content.md#markdown-text": "content/markdown/#standard-syntax-and-extensions",
+    "content.md#semantic-callouts": "content/callouts/",
+    "content.md#tabs": "content/tabs/",
+    "content.md#details-disclosures": "content/details/",
+    "content.md#tables": "content/tables/",
+    "content.md#row-headings": "content/tables/#row-headings",
+    "content.md#sorting": "content/tables/#sorting",
+    "content.md#width-and-scrolling": "content/tables/#width-and-sticky-context",
+    "content.md#code-blocks": "content/code/",
+    "content.md#side-notes": "content/sidenotes/",
+    "content.md#reference-footnotes": "content/footnotes/",
+    "content.md#validation-and-sync": "commands/validate/",
+    "images-and-metadata.md#managed-source-images": "site/images/#source-files",
+    "images-and-metadata.md#managed-image-presentation": "configuration/images/",
+    "images-and-metadata.md#captions-for-tall-images": "configuration/images/#tall-captions-and-inspection",
+    "images-and-metadata.md#inspecting-detailed-images": "configuration/images/#tall-captions-and-inspection",
+    "images-and-metadata.md#markdown-images": "content/markdown/#markdown-images",
+    "images-and-metadata.md#generated-variants-and-static-svg": "site/images/#variants-and-svg",
+    "images-and-metadata.md#manifest": "site/images/#manifest-and-cache",
+    "images-and-metadata.md#metadata-behavior": "site/images/#credits-and-provenance",
+    "images-and-metadata.md#ai-generated-images": "site/images/#credits-and-provenance",
+    "images-and-metadata.md#github-actions-cache": "site/images/#manifest-and-cache",
+    "public-files.md#navigation-logo": "site/public-files/#recognized-files",
+    "public-files.md#browser-icons": "site/public-files/#recognized-files",
+    "public-files.md#social-sharing-image": "site/public-files/#social-previews",
+    "public-files.md#github-pages-custom-domain": "site/public-files/#downloads-and-hosting-files",
+    "public-files.md#generated-sitemap": "site/public-files/#generated-sitemap",
+    "public-files.md#generated-404-page": "site/public-files/#generated-404-page",
+    "public-files.md#other-static-files": "site/public-files/#downloads-and-hosting-files",
+    "public-files.md#generated-copy": "site/public-files/#preparation-and-reserved-paths",
+    "theme.md#theme-presets": "configuration/presets/",
+    "theme.md#choose-a-preset": "configuration/theme/#presets-and-root-overrides",
+    "theme.md#portfolio": "configuration/presets/#portfolio",
+    "theme.md#documentation": "configuration/presets/#documentation",
+    "theme.md#project": "configuration/presets/#project",
+    "theme.md#statement": "configuration/presets/#statement",
+    "theme.md#overrides": "configuration/theme/#presets-and-root-overrides",
+    "theme.md#export-a-preset": "commands/theme/#list-and-export-presets",
+    "theme.md#layout": "configuration/layout/",
+    "theme.md#image-sizing": "configuration/images/",
+    "theme.md#content-block-defaults": "content/cards/#width",
+    "theme.md#typography": "configuration/typography/",
+    "theme.md#palette-and-appearance": "configuration/palettes/",
+    "theme.md#palette": "configuration/palettes/",
+    "theme.md#appearance": "configuration/appearance/",
+    "theme.md#reader-display-controls": "reader/display/",
+    "theme.md#corners": "configuration/theme/#site-wide-settings",
+    "theme.md#section-backgrounds": "configuration/sections/",
+    "theme.md#page-themes": "configuration/theme/#page-themes",
+    "typography.md#typography-profiles": "configuration/typography/#font-profile-and-rhythm",
+    "typography.md#typography-rhythm": "configuration/typography/#font-profile-and-rhythm",
+    "typography.md#configuration-shape": "configuration/typography/#override-fields",
+    "typography.md#override-values": "configuration/typography/#override-fields",
+    "typography.md#page-text-width": "configuration/layout/",
+    "sitewide-content.md#logo": "configuration/shared-content/#logo",
+    "sitewide-content.md#banners": "configuration/shared-content/#banners",
+    "sitewide-content.md#footer": "configuration/shared-content/#footer",
+    "commands.md#cli-commands": "commands/invocation/#command-map",
+    "commands.md#starter-npm-scripts": "commands/invocation/#project-npm-scripts",
+    "commands.md#create-pages-and-categories": "commands/create/",
+    "commands.md#move-a-page": "commands/move/",
+    "commands.md#review-navigation-structure": "commands/navigation/",
+    "commands.md#command-summary": "commands/invocation/#command-map",
+    "local-development.md#start-local-preview": "commands/development/",
+    "local-development.md#test-on-a-phone": "commands/development/#lan-preview",
+    "local-development.md#manage-preview": "commands/development/#lifecycle-commands",
+    "local-development.md#when-startup-fails": "commands/development/#preparation-failures-and-stale-output",
+    "local-development.md#rebuild-stale-preview": "commands/development/#preparation-failures-and-stale-output",
+    "publishing.md#requirements": "workflows/publishing/",
+    "publishing.md#github-pages-workflow": "workflows/publishing/#configure-and-publish",
+    "publishing.md#publish-an-embedded-site-beside-another-static-build": "workflows/embedded-publishing/",
+    "publishing.md#deploy-an-already-committed-branch": "commands/publishing/#deploy-committed-sources",
+    "publishing.md#deploy-with-a-generated-commit": "commands/publishing/#build-and-create-a-commit",
+    "publishing.md#watch-a-deploy": "commands/publishing/#monitor-a-workflow",
+    "upgrading.md#before-changing-the-site": "workflows/upgrading/#establish-the-baseline",
+    "upgrading.md#safest-pre-10-migration": "workflows/upgrading/#older-source-models",
+    "upgrading.md#current-source-layout": "workflows/legacy-source/",
+    "upgrading.md#routine-engine-updates": "workflows/upgrading/#update-and-review",
+    "upgrading.md#validate-the-migration": "workflows/upgrading/#update-and-review",
+    "editor-support.md#install-the-extension": "workflows/editor/#install-and-verify",
+    "editor-support.md#what-you-see-in-vs-code": "workflows/editor/#install-and-verify",
+    "editor-support.md#requirements": "workflows/editor/#install-and-verify",
+    "editor-support.md#recognized-files": "workflows/editor/#recognized-files",
+    "editor-support.md#configuration-help": "workflows/editor/#suggestions-and-diagnostics",
+    "editor-support.md#markdown-and-image-help": "workflows/editor/#managed-images-and-quick-fixes",
+    "editor-support.md#refresh-after-an-engine-change": "workflows/editor/#refresh-and-troubleshoot",
+    "editor-support.md#troubleshooting": "workflows/editor/#refresh-and-troubleshoot",
+    "editor-support.md#turn-off-ai-suggestions-while-keeping-intellisense": "workflows/editor-ai-suggestions/",
+    "client-javascript.md#feature-contract": "reader/accessibility/#without-javascript",
+    "client-javascript.md#choosing-static-alternatives": "reader/accessibility/#without-javascript",
+    "presentation-guarantees.md#color-and-focus": "reader/accessibility/#color-focus-and-controls",
+    "presentation-guarantees.md#typography-and-reading-width": "reader/accessibility/#reading-and-reflow",
+    "presentation-guarantees.md#reflow-and-text-adaptation": "reader/accessibility/#reading-and-reflow",
+    "presentation-guarantees.md#controls-and-user-preferences": "reader/display/",
+    "presentation-guarantees.md#author-responsibilities": "reader/accessibility/#author-responsibilities"
+  }
+}

package/scripts/lib/page-model.mjs

@@ -94,6 +94,28 @@ export const decodePageDirectoryPath = (pageEntryPath, label = 'page entry path'
 	return pageDirectories.join('/pages/');
 };
 
+export const getSiteEntryPrefix = (siteDirLabel) => siteDirLabel
+	.replace(/^[./\\]+/, '')
+	.replace(/[^a-zA-Z0-9-]+/g, '-')
+	.replace(/^-+|-+$/g, '') || 'site';
+
+const getPageEntryPrefix = (siteDirLabel) => `${getSiteEntryPrefix(siteDirLabel)}-page-`;
+
+export const encodePageEntryId = (siteDirLabel, pageDirectoryPath) => (
+	`${getPageEntryPrefix(siteDirLabel)}${encodePageDirectoryPath(pageDirectoryPath)}`
+);
+
+export const decodePageEntryId = (siteDirLabel, entryId) => {
+	const prefix = getPageEntryPrefix(siteDirLabel);
+	if (!entryId.startsWith(prefix)) return null;
+
+	try {
+		return parsePageDirectoryPath(decodePageDirectoryPath(entryId.slice(prefix.length))).pageDirectory;
+	} catch {
+		return null;
+	}
+};
+
 export const getPageDirectoryAncestors = (pageDirectoryPath) => {
 	const { pageDirectories } = parsePageDirectoryPath(pageDirectoryPath);
 	return pageDirectories.map((_, index) => (

package/scripts/lib/schema-definitions.mjs

@@ -209,7 +209,7 @@ const pageAlias = z.string().regex(
 	'Use an old site-relative Norna page URL such as "/guides/install/". Start and end with / and use lowercase letters, numbers, and single hyphens.',
 ).describe('Previous site-relative URL that permanently identifies this page.');
 const pageMetadata = z.object({
-	description: z.string().min(1).optional().describe('Optional page-specific meta description.'),
+	description: z.string().min(1).optional().describe('Page description used in metadata, social previews and generated child-page lists.'),
 	aliases: z.array(pageAlias)
 		.min(1)
 		.refine((values) => new Set(values).size === values.length, 'Page aliases must be unique within the page.')
@@ -275,7 +275,7 @@ const sitewideShape = {
 };
 
 const categoryShape = {
-	label: z.string().trim().min(1).describe('Navigation label for this non-routable page category.'),
+	label: z.string().trim().min(1).describe('Navigation label for a group of child pages without an authored page body.'),
 };
 
 export const schemaTopLevelKeys = Object.freeze({
@@ -290,7 +290,7 @@ export const schemaTopLevelKeys = Object.freeze({
 export const configSchema = z.object(configShape).strict()
 	.describe('Technical settings for one Norna site. Additional pages cannot provide technical configuration.');
 export const categorySchema = z.object(categoryShape).strict()
-	.describe('A non-routable navigation category containing child pages.');
+	.describe('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.');
 export const siteSchema = z.object(siteShape).strict()
 	.describe('Frontmatter for a homepage or additional page content.md file.');
 export const themeVisualSchema = z.object(themeVisualShape).strict()

package/scripts/lib/schema-editor-metadata.mjs

@@ -583,7 +583,7 @@ const addContentHelp = (jsonSchema) => {
 	]);
 	addHelp(jsonSchema, 'page.description', [
 		yamlExample('page:\n  description: About this project.'),
-		'An optional page-specific description rendered as `<meta name="description">`. It is not visible in page content.',
+		'A page-specific description used in metadata and social previews. Generated child-page and category lists can show it beside the page title; it is not inserted into the page body.',
 		documentationLink('Page title and frontmatter reference', 'content.md', 'page-title-and-frontmatter'),
 	], ['About this project.']);
 	addHelp(jsonSchema, 'page.aliases', [

package/src/components/PageAliasRedirect.astro

@@ -1,7 +1,11 @@
 ---
+import { getCollection } from 'astro:content';
+import { getPresentationCssVariables, resolveThemePresentation } from '../../scripts/lib/presentation.mjs';
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { getAbsolutePageUrl } from '../../scripts/lib/site-page-urls.mjs';
+import { siteThemeLabel } from '../../scripts/lib/site-paths.mjs';
 import { withBasePath } from '../lib/basePath';
+import { getReaderPreferencesScript } from '../lib/readerPreferencesScript.mjs';
 
 interface Props {
 	targetPathname: string;
@@ -13,23 +17,54 @@ const { targetPathname, targetTitle, categoryTitle } = Astro.props;
 const { labels, lang } = projectConfig.locale;
 const targetHref = withBasePath(projectConfig.site.basePath, targetPathname);
 const canonicalUrl = getAbsolutePageUrl(projectConfig.site.url, targetPathname);
+const [siteTheme] = await getCollection('theme');
+if (!siteTheme) throw new Error(`${siteThemeLabel} is required. Add a root theme before building the site.`);
+const presentation = resolveThemePresentation(siteTheme.data, siteThemeLabel);
+const documentStyle = Object.entries(getPresentationCssVariables(presentation))
+	.map(([name, value]) => `${name}: ${value}`).join('; ');
+const readerPreferencesScript = getReaderPreferencesScript({
+	...presentation.readerPreferences,
+	cookiePath: projectConfig.site.basePath,
+});
 ---
 
 <!doctype html>
-<html lang={lang} data-pagefind-ignore="all">
+<html lang={lang} data-pagefind-ignore="all" data-appearance={presentation.appearance.default} style={documentStyle}>
 	<head>
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width" />
 		<meta name="robots" content="noindex, follow" />
-		<meta http-equiv="refresh" content={`0; url=${targetHref}`} />
 		<link rel="canonical" href={canonicalUrl} />
 		<title>{categoryTitle ?? labels.pageMoved}: {targetTitle}</title>
+		<meta name="theme-color" content={presentation.palette.page.backgroundColor} />
 		<style is:inline>
 			:root {
-				color-scheme: light dark;
+				--color-page: var(--palette-light-page-background);
+				--color-primary-text: var(--palette-light-primary-text);
+				--color-link-text: var(--palette-light-link-text);
+				color-scheme: light;
+				min-height: 100%;
+				background: var(--color-page);
+				color: var(--color-primary-text);
 				font-family: system-ui, sans-serif;
 			}
 
+			:root[data-appearance='dark'] {
+				--color-page: var(--palette-dark-page-background);
+				--color-primary-text: var(--palette-dark-primary-text);
+				--color-link-text: var(--palette-dark-link-text);
+				color-scheme: dark;
+			}
+
+			@media (prefers-color-scheme: dark) {
+				:root[data-appearance='system'] {
+					--color-page: var(--palette-dark-page-background);
+					--color-primary-text: var(--palette-dark-primary-text);
+					--color-link-text: var(--palette-dark-link-text);
+					color-scheme: dark;
+				}
+			}
+
 			body {
 				margin: 0;
 				padding: 2rem;
@@ -39,7 +74,13 @@ const canonicalUrl = getAbsolutePageUrl(projectConfig.site.url, targetPathname);
 				max-width: 42rem;
 				margin-inline: auto;
 			}
+
+			a {
+				color: var(--color-link-text);
+			}
 		</style>
+		<script is:inline set:html={readerPreferencesScript} />
+		<meta http-equiv="refresh" content={`0; url=${targetHref}`} />
 	</head>
 	<body>
 		<main>

package/src/content.config.ts

@@ -9,17 +9,14 @@ import {
 	siteThemePath,
 	sitewideContentPath,
 } from '../scripts/lib/site-paths.mjs';
-import { encodePageDirectoryPath, parsePageDirectoryPath } from '../scripts/lib/page-model.mjs';
+import { encodePageEntryId, getSiteEntryPrefix, parsePageDirectoryPath } from '../scripts/lib/page-model.mjs';
 import {
 	siteSchema,
 	sitewideSchema,
 	themeVisualSchema,
 } from '../scripts/lib/schema-definitions.mjs';
 
-const siteEntryId = `${siteDirLabel
-	.replace(/^[./\\]+/, '')
-	.replace(/[^a-zA-Z0-9-]+/g, '-')
-	.replace(/^-+|-+$/g, '') || 'site'}-content`;
+const siteEntryPrefix = getSiteEntryPrefix(siteDirLabel);
 const emptyYamlMapping = (value: unknown) => value ?? {};
 const siteThemeSchema = z.preprocess(emptyYamlMapping, themeVisualSchema);
 const sitewideContentSchema = z.preprocess(emptyYamlMapping, sitewideSchema);
@@ -34,7 +31,7 @@ const site = defineCollection({
 				.split('/')
 				.filter((segment) => segment !== 'pages')
 				.join('/pages/');
-			return `${siteEntryId.replace(/-content$/, '')}-page-${encodePageDirectoryPath(parsePageDirectoryPath(pageDirectory, `page directory pages/${pageEntryDirectory}`).pageDirectory)}`;
+			return encodePageEntryId(siteDirLabel, parsePageDirectoryPath(pageDirectory, `page directory pages/${pageEntryDirectory}`).pageDirectory);
 		},
 	}),
 	schema: siteSchema,
@@ -44,7 +41,7 @@ const theme = defineCollection({
 	loader: glob({
 		pattern: basename(siteThemePath),
 		base: pathToFileURL(siteDir),
-		generateId: () => `${siteEntryId.replace(/-content$/, '')}-theme`,
+		generateId: () => `${siteEntryPrefix}-theme`,
 	}),
 	schema: siteThemeSchema,
 });
@@ -53,7 +50,7 @@ const sitewide = defineCollection({
 	loader: glob({
 		pattern: basename(sitewideContentPath),
 		base: pathToFileURL(siteDir),
-		generateId: () => `${siteEntryId.replace(/-content$/, '')}-sitewide`,
+		generateId: () => `${siteEntryPrefix}-sitewide`,
 	}),
 	schema: sitewideContentSchema,
 });

package/src/lib/sitePages.ts

@@ -1,12 +1,12 @@
 import type { CollectionEntry } from 'astro:content';
 import path from 'node:path';
-import { decodePageDirectoryPath, parsePageDirectoryPath } from '../../scripts/lib/page-model.mjs';
+import { decodePageEntryId, parsePageDirectoryPath } from '../../scripts/lib/page-model.mjs';
 import { parsePageMarkdown } from '../../scripts/lib/page-markdown.mjs';
 import { readSiteFile } from '../../scripts/lib/site-content.mjs';
 import { homePageDirectory } from '../../scripts/lib/site-conventions.mjs';
 import { assertCategoryDestinationModel, createCategoryDestinationModel } from '../../scripts/lib/category-destinations.mjs';
 import { getSiteStructure } from '../../scripts/lib/site-structure.mjs';
-import { sitePagesDir, sitePagesLabel } from '../../scripts/lib/site-paths.mjs';
+import { siteDirLabel, sitePagesDir, sitePagesLabel } from '../../scripts/lib/site-paths.mjs';
 
 type SiteEntry = CollectionEntry<'site'>;
 
@@ -48,24 +48,10 @@ export type SiteCategory = SiteNodeBase & {
 
 export type SiteNode = SitePage | SiteCategory;
 
-const pageIdMarker = '-page-';
-
-const stripPageIdPrefix = (id: string) => {
-	const markerIndex = id.lastIndexOf(pageIdMarker);
-	if (markerIndex === -1) return null;
-
-	const candidate = id.slice(markerIndex + pageIdMarker.length);
-	try {
-		return parsePageDirectoryPath(decodePageDirectoryPath(candidate)).pageDirectory;
-	} catch {
-		return null;
-	}
-};
-
-export const isHomePageEntry = (entry: SiteEntry) => stripPageIdPrefix(entry.id) === homePageDirectory;
+export const isHomePageEntry = (entry: SiteEntry) => decodePageEntryId(siteDirLabel, entry.id) === homePageDirectory;
 
 export const getPageDirectory = (entry: SiteEntry) => {
-	const pageDirectory = stripPageIdPrefix(entry.id);
+	const pageDirectory = decodePageEntryId(siteDirLabel, entry.id);
 	if (!pageDirectory) throw new Error(`Page entry "${entry.id}" has no valid page directory.`);
 	return pageDirectory;
 };

package/src/styles/content.css

@@ -983,8 +983,9 @@ ul {
 	padding: 0.78rem 0.9rem;
 	background: var(--color-code-background) !important;
 	color: var(--color-code-text);
-	font-size: 0.92em;
-	line-height: 1.45;
+	font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+	font-size: 0.875rem;
+	line-height: 1.43;
 	text-align: left;
 }
 

package/starters/basic/README.md

@@ -61,5 +61,5 @@ Use `npm run norna:engine:version` to inspect the installed engine and
 `npm run norna:engine:update` to update it.
 
 Start with the [illustrated Getting Started guide](https://janga.github.io/norna/getting-started/install-norna/).
-Use the [Markdown reference index](https://github.com/janga/norna/blob/main/docs/README.md)
+Use the [Norna reference](https://janga.github.io/norna/reference/)
 for exact file contracts, syntax, commands, and publishing behavior.