@janga/norna 0.7.25 → 0.7.26

package/scripts/lib/site-link-graph.mjs

@@ -17,6 +17,7 @@ import {
 } from './site-paths.mjs';
 import { getSiteNodePathname } from './site-page-urls.mjs';
 import { getSiteStructure } from './site-structure.mjs';
+import { createCategoryDestinationModel } from './category-destinations.mjs';
 
 const internalUrlOrigin = 'https://norna.invalid';
 const externalSchemePattern = /^[a-z][a-z0-9+.-]*:/i;
@@ -161,6 +162,13 @@ export const createSiteLinkGraph = ({
 		return createPageRecord(pageDocument);
 	});
 	const pagesByPathname = new Map(pages.map((page) => [page.pathname, page]));
+	const pagesByDirectory = new Map(pages.map((page) => [page.contentFile.pageDirectory, page]));
+	const categoryModel = createCategoryDestinationModel(siteStructure.nodes.map((node) => ({
+		...node,
+		navigation: node.kind === 'page'
+			? pagesByDirectory.get(node.pageDirectory).navigation
+			: { listed: true },
+	})));
 	const categoriesByPathname = new Map(siteStructure.categories.map((category) => [
 		getSiteNodePathname(category),
 		{ ...category, pathname: getSiteNodePathname(category) },
@@ -185,7 +193,7 @@ export const createSiteLinkGraph = ({
 
 	const references = [];
 	const referencesByTarget = new Map();
-	const diagnostics = [...aliasModel.diagnostics];
+	const diagnostics = [...aliasModel.diagnostics, ...categoryModel.diagnostics];
 
 	for (const page of pages) {
 		for (const sourceReference of page.document.links) {
@@ -278,13 +286,14 @@ export const createSiteLinkGraph = ({
 			const targetCategory = target.pageLookupPathname
 				? categoriesByPathname.get(target.pageLookupPathname)
 				: null;
-			if (targetCategory) {
+			if (targetCategory && categoryModel.byPathname.has(targetCategory.pathname)) {
 				reference.resolution = { category: targetCategory, kind: 'category', pathname: targetCategory.pathname };
-				diagnostics.push(createIssue(
+				const destination = categoryModel.byPathname.get(targetCategory.pathname);
+				if (target.fragment && !(destination.kind === 'listing' && target.fragment === 'page-title')) diagnostics.push(createIssue(
 					reference,
-					'category-has-no-url',
-					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to navigation category ${targetCategory.pathname}, which does not have its own page.`,
-					'Link to one of the category pages, or replace category.yaml with content.md when the collection needs its own page.',
+					'missing-internal-anchor',
+					`Internal link "${sourceReference.target}" on line ${sourceReference.line} points to an unavailable category anchor.`,
+					'Link to the category without a fragment, or use the content page URL for a heading link.',
 				));
 				continue;
 			}
@@ -318,6 +327,7 @@ export const createSiteLinkGraph = ({
 	}
 
 	return {
+		categoryModel,
 		aliasModel,
 		aliases: aliasModel.aliases,
 		aliasesByPathname: aliasModel.aliasesByPathname,

package/scripts/lib/site-navigation-tree.mjs

@@ -37,17 +37,6 @@ export const getListedSiteNavigationTree = (entries) => {
 	return filterListed(getSiteNavigationTree(entries));
 };
 
-export const getFirstPageInNavigationNode = (node) => {
-	if (node.node.kind === 'page') return node.node;
-
-	for (const child of node.children) {
-		const page = getFirstPageInNavigationNode(child);
-		if (page) return page;
-	}
-
-	return null;
-};
-
 export const flattenSiteNavigationTree = (nodes) => nodes.flatMap((node) => [
 	node,
 	...flattenSiteNavigationTree(node.children),

package/scripts/lib/sitemap.mjs

@@ -11,9 +11,11 @@ const escapeXml = (value) => String(value)
 
 const compareStrings = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 
-export const getSitemapUrls = ({ siteStructure, siteUrl }) => (
-	siteStructure.contentFiles
-		.map((page) => getSiteNodePathname(page))
+export const getSitemapUrls = ({ siteStructure, siteUrl, categoryDestinations = [] }) => (
+	[
+		...siteStructure.contentFiles.map((page) => getSiteNodePathname(page)),
+		...categoryDestinations.filter(({ kind }) => kind === 'listing').map(({ pathname }) => pathname),
+	]
 		.sort(compareStrings)
 		.map((pathname) => getAbsolutePageUrl(siteUrl, pathname))
 );

package/scripts/lib/structured-blocks.mjs

@@ -0,0 +1,108 @@
+import { isAlias, isMap, isScalar, isSeq, LineCounter, parseDocument } from 'yaml';
+
+const stringSchema = (name, definition) => ({
+	type: 'string',
+	description: definition.description,
+	...(definition.default !== undefined ? { default: definition.default } : {}),
+	...(definition.values ? { enum: Object.keys(definition.values) } : {}),
+	...(name === 'alt' ? {} : { minLength: 1 }),
+	pattern: name === 'image'
+		? '^[a-zA-Z0-9][a-zA-Z0-9.-]*\\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[sS][vV][gG])$(?![\\s\\S])'
+		: name === 'caption' || name === 'text'
+			? '^(?=[\\s\\S]*\\S)[^\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F\\x7F-\\x9F]*$(?![\\s\\S])'
+			: name === 'alt'
+				? '^(?:|(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+)$(?![\\s\\S])'
+				: '^(?=.*\\S)[^\\x00-\\x1F\\x7F-\\x9F\\u2028\\u2029]+$(?![\\s\\S])',
+});
+
+export const createStructuredBlockSchema = (definition) => {
+	if (!definition?.item) return null;
+	const fields = { [definition.item.start.key]: definition.item.start, ...definition.item.fields };
+	const item = {
+		type: 'object',
+		additionalProperties: false,
+		required: [definition.item.start.key],
+		properties: Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, stringSchema(key, field)])),
+		...(definition.item.start.key === 'title' ? {
+			anyOf: ['text', 'image', 'link'].map((key) => ({ required: [key] })),
+		} : {}),
+	};
+	return {
+		$schema: 'https://json-schema.org/draft/2020-12/schema',
+		description: definition.description,
+		type: 'object',
+		additionalProperties: false,
+		required: ['items'],
+		properties: {
+			...Object.fromEntries(Object.entries(definition.options ?? {}).map(([key, field]) => [key, stringSchema(key, field)])),
+			items: { type: 'array', minItems: definition.minItems ?? 1, items: item },
+		},
+	};
+};
+
+// Validate the AST directly so errors and later link edits retain exact source ranges.
+export const parseStructuredBlock = (source, schema, options = {}) => {
+	const lines = new LineCounter();
+	const document = parseDocument(source, { schema: 'core', version: '1.2', uniqueKeys: true, lineCounter: lines });
+	const lineAt = (node) => (options.line ?? 1) + lines.linePos(node?.range?.[0] ?? 0).line - 1;
+	const fail = (message, node) => {
+		const line = lineAt(node);
+		throw Object.assign(new Error(`${options.label ? `${options.label} ` : ''}line ${line}: ${options.type}: ${message}`), { line });
+	};
+	if (document.errors.length) {
+		const error = document.errors[0];
+		fail(`Invalid YAML: ${error.message.split('\n')[0]}`, { range: error.pos });
+	}
+	if (document.directives.yaml.version !== '1.2') fail('Use YAML 1.2 Core; other YAML versions are not supported.', document.contents);
+	const validate = (node, rule, path, depth = 0) => {
+		if (depth > 16) fail('YAML nesting is too deep.', node);
+		if (node?.anchor || node?.tag || isAlias(node)) fail('YAML anchors, aliases, and explicit tags are not allowed.', node);
+		if (rule.type === 'object') {
+			if (!isMap(node)) fail(`${path} must be a YAML mapping${path === 'Block' ? ' with an items list' : ''}.`, node);
+			const result = {};
+			for (const pair of node.items) {
+				if (!isScalar(pair.key) || typeof pair.key.value !== 'string') fail(`${path} field names must be strings.`, pair.key);
+				if (pair.key.tag || pair.key.anchor) fail('YAML anchors and explicit tags are not allowed.', pair.key);
+				const key = pair.key.value;
+				if (!Object.hasOwn(rule.properties, key)) fail(`Unknown ${path} field "${key}".`, pair.key);
+				result[key] = validate(pair.value, rule.properties[key], `${path}.${key}`, depth + 1);
+			}
+			for (const key of rule.required ?? []) {
+				if (!Object.hasOwn(result, key)) fail(`${path} is missing "${key}".`, node);
+			}
+			if (rule.anyOf && !rule.anyOf.some((alternative) => alternative.required.every((key) => Object.hasOwn(result, key)))) {
+				fail(`${path} must specify at least one of text, image, or link.`, node);
+			}
+			return result;
+		}
+		if (rule.type === 'array') {
+			if (!isSeq(node)) fail(`${path} must be a YAML list.`, node);
+			if (node.items.length < rule.minItems) fail(`${path} must contain at least ${rule.minItems} item.`, node);
+			return node.items.map((item, index) => validate(item, rule.items, `${path}[${index + 1}]`, depth + 1));
+		}
+		if (!isScalar(node) || typeof node.value !== 'string') fail(`${path} must be a string; quote values that YAML would interpret as numbers, booleans, or null.`, node);
+		if (rule.enum && !rule.enum.includes(node.value)) fail(`Invalid ${path} "${node.value}". Use one of: ${rule.enum.join(', ')}.`, node);
+		if (!new RegExp(rule.pattern).test(node.value)) {
+			fail(path.endsWith('.image')
+				? 'Image reference must be a filename ending in jpg, jpeg, png, or svg.'
+				: `${path} must ${path.endsWith('.alt') ? 'be empty or contain single-line text' : 'contain non-empty text'}${/\.(caption|text)$/.test(path) ? '' : ' without line breaks or control characters'}.`, node);
+		}
+		return node.value;
+	};
+	const data = validate(document.contents, schema, 'Block');
+	const items = document.get('items', true).items;
+	data.items = data.items.map((item, index) => {
+		const node = items[index];
+		const link = node.get('link', true);
+		return {
+			...item,
+			line: lineAt(node),
+			...(link ? {
+				linkLine: lineAt(link),
+				// A block scalar owns its trailing newline; leave that separator in place when editing the value.
+				linkRange: { start: link.range[0], end: source.slice(0, link.range[1]).trimEnd().length },
+			} : {}),
+		};
+	});
+	return data;
+};

package/scripts/lib/table-render-plugin.mjs

@@ -1,16 +1,59 @@
 import { defineHastPlugin } from 'satteri';
 
+const transformTableSection = (section, { columnHeaders = false, rowHeaders = false } = {}) => ({
+	...section,
+	children: (section.children ?? []).map((child) => {
+		if (child.type !== 'element' || child.tagName !== 'tr') return child;
+		let columnIndex = 0;
+		return {
+			...child,
+			children: (child.children ?? []).map((cell) => {
+				if (cell.type !== 'element' || (cell.tagName !== 'th' && cell.tagName !== 'td')) return cell;
+				const currentColumn = columnIndex;
+				columnIndex += 1;
+				if (columnHeaders) {
+					return {
+						...cell,
+						properties: { ...(cell.properties ?? {}), scope: 'col' },
+					};
+				}
+				if (rowHeaders && currentColumn === 0) {
+					return {
+						...cell,
+						tagName: 'th',
+						properties: { ...(cell.properties ?? {}), scope: 'row' },
+					};
+				}
+				return cell;
+			}),
+		};
+	}),
+});
+
+const transformRowHeaderTable = (node) => ({
+	...node,
+	children: (node.children ?? []).map((child) => {
+		if (child.type !== 'element') return child;
+		if (child.tagName === 'thead') return transformTableSection(child, { columnHeaders: true });
+		if (child.tagName === 'tbody') return transformTableSection(child, { rowHeaders: true });
+		return child;
+	}),
+});
+
 export const nornaTableRenderPlugin = defineHastPlugin({
 	name: 'norna-table-render',
 	element: {
 		filter: ['table'],
 		visit(node, context) {
+			const hasRowHeaders = node.properties?.['data-row-headers'] === 'true';
+			const table = hasRowHeaders ? transformRowHeaderTable(node) : node;
 			context.replaceNode(node, {
 				type: 'element',
 				tagName: 'div',
 				properties: {
 					className: ['norna-table-frame', 'content-block-note-lane-boundary'],
 					'data-table-frame': '',
+					...(hasRowHeaders ? { 'data-table-row-headers': 'true' } : {}),
 				},
 				children: [{
 					type: 'element',
@@ -22,9 +65,9 @@ export const nornaTableRenderPlugin = defineHastPlugin({
 					},
 					children: [{
 						type: 'element',
-						tagName: node.tagName,
-						properties: { ...(node.properties ?? {}) },
-						children: [...(node.children ?? [])],
+						tagName: table.tagName,
+						properties: { ...(table.properties ?? {}) },
+						children: [...(table.children ?? [])],
 					}],
 				}],
 			});

package/scripts/lib/table-row-headers.mjs

@@ -0,0 +1,218 @@
+export const tableRowHeaderMarker = '{row-header}';
+
+const trailingMarkerPattern = /\s*\{row-header\}\s*$/u;
+
+const getNodeText = (node) => {
+	if (!node || typeof node !== 'object') return '';
+	if (node.type === 'text' || node.type === 'inlineCode') return node.value ?? '';
+	if (node.type === 'image') return node.alt ?? '';
+	if (!Array.isArray(node.children)) return '';
+	return node.children.map(getNodeText).join('');
+};
+
+const getUnescapedMarkerIndexes = (source) => {
+	const indexes = [];
+	let searchFrom = 0;
+	while (searchFrom < source.length) {
+		const index = source.indexOf(tableRowHeaderMarker, searchFrom);
+		if (index < 0) break;
+		let backslashes = 0;
+		for (let cursor = index - 1; cursor >= 0 && source[cursor] === '\\'; cursor -= 1) {
+			backslashes += 1;
+		}
+		if (backslashes % 2 === 0) indexes.push(index);
+		searchFrom = index + tableRowHeaderMarker.length;
+	}
+	return indexes;
+};
+
+const getTextNodeMarkerCount = (node, source) => {
+	if (node.type !== 'text' || !node.value?.includes(tableRowHeaderMarker)) return 0;
+	const start = node.position?.start.offset;
+	const end = node.position?.end.offset;
+	const raw = Number.isInteger(start) && Number.isInteger(end)
+		? source.slice(start, end)
+		: node.value;
+	return getUnescapedMarkerIndexes(raw).length;
+};
+
+const collectCellMarkers = (node, source, markers, location) => {
+	if (!node || typeof node !== 'object') return;
+	const count = getTextNodeMarkerCount(node, source);
+	for (let index = 0; index < count; index += 1) {
+		markers.push({ ...location, node });
+	}
+	for (const child of node.children ?? []) {
+		collectCellMarkers(child, source, markers, location);
+	}
+};
+
+const normalizeLabel = (value) => value.trim().replace(/\s+/gu, ' ').toLowerCase();
+
+const issue = (code, node, message, fix, otherNode = null) => ({
+	code,
+	fix,
+	message,
+	node,
+	otherNode,
+});
+
+export const inspectTableRowHeaders = (table, source = '') => {
+	if (table?.type !== 'table') return { declared: false, issues: [], valid: false };
+
+	const rows = table.children ?? [];
+	const markers = [];
+	for (const [rowIndex, row] of rows.entries()) {
+		for (const [columnIndex, cell] of (row.children ?? []).entries()) {
+			collectCellMarkers(cell, source, markers, { cell, columnIndex, rowIndex });
+		}
+	}
+
+	if (markers.length === 0) return { declared: false, issues: [], valid: false };
+
+	const issues = [];
+	const declaration = markers[0];
+	for (const repeated of markers.slice(1)) {
+		issues.push(issue(
+			'repeated-table-row-header-marker',
+			repeated.cell,
+			`A table may contain ${tableRowHeaderMarker} only once.`,
+			`Keep ${tableRowHeaderMarker} only in the first column heading.`,
+			declaration.cell,
+		));
+	}
+
+	const firstHeadingCell = rows[0]?.children?.[0];
+	if (declaration.rowIndex !== 0 || declaration.columnIndex !== 0) {
+		issues.push(issue(
+			'invalid-table-row-header-column',
+			declaration.cell,
+			`${tableRowHeaderMarker} must appear in the first column heading.`,
+			`Move ${tableRowHeaderMarker} to the end of the first heading cell.`,
+		));
+	} else if (!getNodeText(firstHeadingCell).trim().endsWith(tableRowHeaderMarker)) {
+		issues.push(issue(
+			'invalid-table-row-header-marker-position',
+			firstHeadingCell,
+			`${tableRowHeaderMarker} must be the final content in the first column heading.`,
+			`Move ${tableRowHeaderMarker} to the end of the first heading cell.`,
+		));
+	}
+
+	const headingLabel = getNodeText(firstHeadingCell).replace(trailingMarkerPattern, '').trim();
+	if (!headingLabel) {
+		issues.push(issue(
+			'empty-table-row-header-heading',
+			firstHeadingCell ?? table,
+			'The row-header column needs a visible column heading.',
+			`Write a heading before ${tableRowHeaderMarker}, for example "Feature ${tableRowHeaderMarker}".`,
+		));
+	}
+
+	if (rows.length < 2) {
+		issues.push(issue(
+			'empty-table-row-header-body',
+			table,
+			'A table with a row-header declaration needs at least one body row.',
+			'Add a body row or remove the row-header declaration.',
+		));
+	}
+
+	const labels = new Map();
+	for (const row of rows.slice(1)) {
+		const cell = row.children?.[0];
+		if (!cell) {
+			issues.push(issue(
+				'missing-table-row-header',
+				row,
+				'This table row has no cell in the row-header column.',
+				'Add a unique row label in the first column.',
+			));
+			continue;
+		}
+
+		const label = getNodeText(cell).trim().replace(/\s+/gu, ' ');
+		if (!label) {
+			issues.push(issue(
+				'empty-table-row-header',
+				cell,
+				'This table row has an empty row header.',
+				'Add a unique row label in the first column.',
+			));
+			continue;
+		}
+
+		const normalizedLabel = normalizeLabel(label);
+		const existing = labels.get(normalizedLabel);
+		if (existing) {
+			issues.push(issue(
+				'duplicate-table-row-header',
+				cell,
+				`Row header "${label}" is repeated.`,
+				'Give every row a unique label so its header association is unambiguous.',
+				existing,
+			));
+			continue;
+		}
+		labels.set(normalizedLabel, cell);
+	}
+
+	return {
+		declared: true,
+		firstHeadingCell,
+		issues,
+		markerNode: declaration.node,
+		valid: issues.length === 0,
+	};
+};
+
+const formatDiagnostic = (entry, options) => {
+	const lineOffset = options.lineOffset ?? 0;
+	const line = lineOffset + (entry.node?.position?.start.line ?? 1);
+	const otherLine = entry.otherNode
+		? lineOffset + (entry.otherNode.position?.start.line ?? 1)
+		: null;
+	const related = otherLine && otherLine !== line ? ` The first occurrence is on line ${otherLine}.` : '';
+	const label = options.label ?? 'Markdown';
+	return {
+		code: entry.code,
+		fix: entry.fix,
+		line,
+		message: `${label} line ${line}: ${entry.message}${related}`,
+		offset: entry.node?.position?.start.offset ?? 0,
+	};
+};
+
+export const getTableRowHeaderDiagnostics = (tree, options = {}) => {
+	const diagnostics = [];
+	const source = options.source ?? '';
+	const visit = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === 'table') {
+			const inspection = inspectTableRowHeaders(node, source);
+			diagnostics.push(...inspection.issues.map((entry) => formatDiagnostic(entry, options)));
+		}
+		for (const child of node.children ?? []) visit(child);
+	};
+	visit(tree);
+	return diagnostics;
+};
+
+export const applyTableRowHeaderDeclaration = (table, context) => {
+	const inspection = inspectTableRowHeaders(table, context.source);
+	if (!inspection.valid || !inspection.markerNode) return false;
+
+	context.setProperty(
+		inspection.markerNode,
+		'value',
+		inspection.markerNode.value.replace(trailingMarkerPattern, ''),
+	);
+	context.setProperty(table, 'data', {
+		...(table.data ?? {}),
+		hProperties: {
+			...(table.data?.hProperties ?? {}),
+			'data-row-headers': 'true',
+		},
+	});
+	return true;
+};

package/scripts/lib/theme-presets.mjs

@@ -50,25 +50,21 @@ export const themePresetDefinitions = Object.freeze({
 		title: 'Portfolio',
 		description: 'For portfolios and image-led sites, with restrained typography and generous space for images.',
 		recipe: themePresetRecipes.portfolio,
-		readerControls: Object.freeze({ appearance: true }),
 	}),
 	documentation: Object.freeze({
 		title: 'Documentation',
 		description: 'For guides and reference material, with reading-focused typography and compact spacing.',
 		recipe: themePresetRecipes.documentation,
-		readerControls: Object.freeze({ appearance: true, focusReading: true }),
 	}),
 	project: Object.freeze({
 		title: 'Project',
 		description: 'For project and product sites that balance explanation, code, cards, and images.',
 		recipe: themePresetRecipes.project,
-		readerControls: Object.freeze({ appearance: true, focusReading: true }),
 	}),
 	statement: Object.freeze({
 		title: 'Statement',
 		description: 'For short, expressive sites, with larger typography, airy spacing, and stronger section emphasis.',
 		recipe: themePresetRecipes.statement,
-		readerControls: Object.freeze({ appearance: true }),
 	}),
 });
 
@@ -82,7 +78,6 @@ export const themePresets = Object.freeze(Object.fromEntries(
 				themePresetDefinitions[name].recipe,
 				`${name} theme preset`,
 			),
-			readerControls: themePresetDefinitions[name].readerControls,
 		}),
 	]),
 ));
@@ -179,7 +174,7 @@ const responsiveValueLines = (label, value, indent = 2) => {
 export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml') => {
 	const preset = getThemePreset(presetName, sourceLabel);
 	const metadata = getThemePresetMetadata(presetName);
-	const { appearance, readerControls, corners, layout, images, blocks, typography, palette, sections } = preset;
+	const { appearance, corners, layout, images, blocks, typography, palette, sections } = preset;
 
 	return [
 		`# Original values for Norna's "${presetName}" theme preset.`,
@@ -193,10 +188,8 @@ export const renderThemePresetReference = (presetName, sourceLabel = 'theme.yaml
 		'appearance:',
 		`  default: ${appearance.default}`,
 		'',
-		'# Optional reader controls shown with the always-available reading-width choice.',
-		'readerControls:',
-		`  appearance: ${readerControls.appearance === true}`,
-		`  focusReading: ${readerControls.focusReading === true}`,
+		'# Appearance and reading width are always available in the Display panel.',
+		'# Focus reading is available automatically when navigation resolves to tree.',
 		'',
 		'# Alternatives: square, rounded.',
 		`corners: ${corners}`,

package/scripts/lib/yaml-config.mjs

@@ -36,12 +36,8 @@ const getLegacyThemeHint = (issue, data) => {
 		return 'Theme setting "colorMode" was replaced by "appearance".';
 	}
 
-	if (location === 'readerControls' && issue.keys?.includes('colorMode')) {
-		return 'Reader control "colorMode" was replaced by "appearance".';
-	}
-
-	if (location === 'readerControls' && issue.keys?.includes('readingWidth')) {
-		return 'Reader control "readingWidth" was removed because reading width is now always available. Remove this field.';
+	if (location === 'readerControls') {
+		return 'Theme setting "readerControls" was removed. Appearance and reading width are always available; Focus reading follows tree navigation. Remove this block.';
 	}
 
 	return undefined;

package/scripts/migrate-check.mjs

@@ -0,0 +1,19 @@
+import {
+	auditDocusaurusProject,
+	migrationCheckUsage,
+	parseMigrationCheckArgs,
+	writeMigrationReport,
+} from './lib/docusaurus-migration-audit.mjs';
+
+const parsed = parseMigrationCheckArgs(process.argv.slice(2));
+if (parsed.help) {
+	console.log(migrationCheckUsage);
+	process.exit(0);
+}
+
+const report = await auditDocusaurusProject({ sourceRoot: parsed.sourceRoot });
+await writeMigrationReport(report, parsed.reportDir, { sourceRoot: parsed.sourceRoot });
+console.log('Docusaurus migration audit written to ' + parsed.reportDir);
+console.log('Source pages: ' + report.summary.pages);
+console.log('Pages requiring attention: ' + report.summary.pagesWithFindings);
+console.log('Findings: ' + report.summary.findings);

package/scripts/sync-content-sections.mjs

@@ -233,6 +233,7 @@ try {
 const siteStructure = await getSiteStructure();
 const contentFiles = siteStructure.contentFiles;
 for (const warning of siteStructure.warnings) {
+	if (warning.code === 'empty-category') continue;
 	addIssue({
 		severity: 'warning',
 		message: warning.message,
@@ -272,6 +273,14 @@ for (const contentFile of contentFiles) {
 		prelude,
 		regions: sections,
 	} = page;
+	for (const issue of page.diagnostics.filter((candidate) => candidate.code === 'heading-inside-details')) {
+		addContentIssue(contentFile, issue);
+	}
+	for (const issue of page.noteDiagnostics) {
+		const section = sections.find((candidate) => issue.offset >= candidate.startOffset && issue.offset < candidate.endOffset);
+		if (section) addSectionIssue(contentFile, section, issue);
+		else addContentIssue(contentFile, issue);
+	}
 	const invalidHeadingLines = new Set();
 	for (const issue of headingIdentifierIssues) {
 		invalidHeadingLines.add(issue.heading.line);
@@ -362,14 +371,19 @@ for (const contentFile of contentFiles) {
 		const blockResults = { blocks: section.blocks, errors: section.blockErrors };
 		blockResultsBySection.set(section, blockResults);
 
-		for (const error of section.noteErrors) {
+		for (const error of section.tabErrors) {
+			addSectionIssue(contentFile, section, { severity: 'error', message: error.message });
+		}
+
+		for (const error of section.calloutErrors) {
 			addSectionIssue(contentFile, section, {
-				severity: 'error',
+				severity: error.severity ?? 'error',
 				message: error.message,
+				fix: error.fix,
 			});
 		}
 
-		for (const error of section.calloutErrors) {
+		for (const error of section.codeFenceErrors) {
 			addSectionIssue(contentFile, section, {
 				severity: 'error',
 				message: error.message,
@@ -377,7 +391,7 @@ for (const contentFile of contentFiles) {
 			});
 		}
 
-		for (const error of section.codeFenceErrors) {
+		for (const error of section.tableErrors) {
 			addSectionIssue(contentFile, section, {
 				severity: 'error',
 				message: error.message,
@@ -421,17 +435,32 @@ const listedNavigationTree = getListedSiteNavigationTree(siteStructure.nodes.map
 
 for (const context of contentFileContexts) {
 	const childPages = getDirectChildPages(listedNavigationTree, context.contentFile.pagePath);
-	if (childPages.length > 0) continue;
+	const warnedChildren = new Set();
 
 	for (const section of context.sections) {
 		if (!context.validSections.has(section)) continue;
 		for (const block of section.blocks) {
 			if (block.type !== 'page-list') continue;
-			addSectionIssue(context.contentFile, section, {
-				severity: 'error',
-				message: `page-list on line ${block.line} has no listed direct child pages to display. Navigation categories are not pages.`,
-				fix: 'Add a listed direct child page or remove the block.',
-			});
+			if (childPages.length === 0) {
+				addSectionIssue(context.contentFile, section, {
+					severity: 'error',
+					message: `page-list on line ${block.line} has no listed direct child pages to display. Navigation categories are not pages.`,
+					fix: 'Add a listed direct child page or remove the block.',
+				});
+				continue;
+			}
+			for (const child of childPages) {
+				const childContext = contentContextByPageDirectory.get(child.pageDirectory);
+				if (!childContext || warnedChildren.has(child.pageDirectory)) continue;
+				const description = childContext.frontmatterData.page?.description;
+				if (typeof description === 'string' && description.trim()) continue;
+				warnedChildren.add(child.pageDirectory);
+				addSectionIssue(context.contentFile, section, {
+					severity: 'warning',
+					message: `page-list on line ${block.line} includes ${childContext.contentFile.contentLabel} without a non-empty page.description.`,
+					fix: 'Add page.description to that child file\'s frontmatter. Explain what the reader will find or when to choose this page, rather than repeating its title.',
+				});
+			}
 		}
 	}
 }