@umami/shiso 1.11.0 → 1.12.0

package/docs.schema.json

@@ -172,6 +172,37 @@
           ],
           "description": "Page eyebrow style: the section name (default) or the full navigation path.",
           "default": "section"
+        },
+        "codeBlocks": {
+          "type": "object",
+          "description": "Fenced code block defaults: line numbers and the Shiki light/dark themes.",
+          "additionalProperties": false,
+          "properties": {
+            "$ref": { "$ref": "#/definitions/configRef" },
+            "lineNumbers": {
+              "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+              "description": "Show line numbers on every block. Override per block with showLineNumbers or hideLineNumbers in the fence meta.",
+              "default": false
+            },
+            "theme": {
+              "type": "object",
+              "description": "Bundled Shiki theme names for each color mode (https://shiki.style/themes).",
+              "additionalProperties": false,
+              "properties": {
+                "$ref": { "$ref": "#/definitions/configRef" },
+                "light": {
+                  "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+                  "description": "Theme used in light mode.",
+                  "default": "github-light"
+                },
+                "dark": {
+                  "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+                  "description": "Theme used in dark mode.",
+                  "default": "github-dark"
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -567,6 +598,24 @@
         }
       }
     },
+    "api": {
+      "type": "object",
+      "description": "API reference settings: the OpenAPI spec powering openapi frontmatter pages.",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["spec"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "spec": {
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Path to a local OpenAPI 3.0 or 3.1 spec (JSON or YAML), relative to the project root."
+        },
+        "directory": {
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Folder inside the content directory for generated endpoint pages.",
+          "default": "api-reference"
+        }
+      }
+    },
     "errors": {
       "type": "object",
       "description": "Error handling settings.",
@@ -712,6 +761,8 @@
           "description": "Page reference relative to the content directory, without extension (e.g. \"components/tabs\")."
         },
         { "$ref": "#/definitions/pageObject" },
+        { "$ref": "#/definitions/globItem" },
+        { "$ref": "#/definitions/openapiItem" },
         { "$ref": "#/definitions/linkItem" },
         { "$ref": "#/definitions/group" }
       ]
@@ -736,12 +787,51 @@
         },
         "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the label." },
         "tag": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Short label shown after the page name." },
+        "method": {
+          "anyOf": [
+            { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"] },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "HTTP method badge shown after the page name on API reference pages."
+        },
         "hidden": {
           "allOf": [{ "$ref": "#/definitions/booleanValue" }],
           "description": "Hide from the sidebar and search. The page is still built and reachable by URL."
         }
       }
     },
+    "globItem": {
+      "type": "object",
+      "required": ["glob"],
+      "additionalProperties": false,
+      "properties": {
+        "glob": {
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Glob relative to contentDir. Matching Markdown and MDX files are expanded into page entries."
+        },
+        "exclude": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": { "$ref": "#/definitions/nonEmptyStringValue" }
+            },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "Optional glob patterns to omit from the matches."
+        }
+      }
+    },
+    "openapiItem": {
+      "type": "object",
+      "required": ["openapi"],
+      "additionalProperties": false,
+      "properties": {
+        "openapi": {
+          "anyOf": [{ "type": "boolean" }, { "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Expand API endpoints into pages: true for every tag (grouped), or a tag name for that tag's operations. Requires the api.spec setting."
+        }
+      }
+    },
     "linkItem": {
       "type": "object",
       "description": "An external link in the navigation tree.",

package/mdx.config.ts

@@ -1,104 +1,19 @@
 import mdx from '@mdx-js/rollup';
 import rehypeAutolinkHeadings from 'rehype-autolink-headings';
-import rehypeHighlight from 'rehype-highlight';
 import rehypeSlug from 'rehype-slug';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
 import type { Plugin } from 'vite';
-import { type MdNode, toText, walkTree } from './src/lib/mdast.ts';
+import { resolveCodeBlockConfig } from './src/lib/code-blocks.ts';
+import { type MdNode, toText } from './src/lib/mdast.ts';
+import { rehypeShiki } from './src/lib/rehype-shiki.ts';
 import { remarkToc } from './src/lib/remark-toc.ts';
+import type { MdxConfig, ResolvedCodeBlockConfig } from './src/lib/types.ts';
 
-const SYNTHETIC_FRAGMENT = 'data-shiso-synthetic-fragment';
-
-function remarkCodeTitles() {
-  return (tree: MdNode) => {
-    const visit = (node: MdNode) => {
-      if (node.type === 'code' && node.meta?.trim()) {
-        const meta = node.meta.trim();
-        const titleMatch = meta.match(/(?:^|\s)title=(?:"([^"]+)"|'([^']+)'|([^\s]+))/);
-        const title = titleMatch ? titleMatch[1] || titleMatch[2] || titleMatch[3] : meta;
-        const hProperties = (node.data?.hProperties || {}) as Record<string, unknown>;
-        node.data = {
-          ...node.data,
-          hProperties: { ...hProperties, 'data-title': title },
-        };
-      }
-
-      node.children?.forEach(visit);
-    };
-
-    visit(tree);
-  };
-}
-
-function rehypeWrapJsxForHighlighting() {
-  return (tree: MdNode) => {
-    walkTree(tree, node => {
-      if (node.tagName !== 'code') {
-        return;
-      }
-
-      const properties = (node.properties || {}) as Record<string, unknown>;
-      const className = properties.className;
-      const classes = Array.isArray(className) ? className.map(String) : [String(className || '')];
-      const source = toText(node);
-
-      if (!classes.some(value => /\blanguage-(?:jsx|tsx)\b/.test(value))) {
-        return;
-      }
-
-      if (!/^\s*<[A-Z][\w.]*(?:\s|>|\/)/.test(source)) {
-        return;
-      }
-
-      properties[SYNTHETIC_FRAGMENT] = true;
-      node.properties = properties;
-      node.children = [{ type: 'text', value: `<>\n${source}\n</>` }];
-    });
-  };
-}
-
-function boundaryText(node: MdNode, fromEnd = false): MdNode | undefined {
-  if (node.type === 'text' && typeof node.value === 'string') {
-    return node;
-  }
-
-  const children = fromEnd ? [...(node.children || [])].reverse() : node.children || [];
-  for (const child of children) {
-    const match = boundaryText(child, fromEnd);
-    if (match) {
-      return match;
-    }
-  }
-
-  return undefined;
-}
-
-function rehypeRemoveHighlightingFragments() {
-  return (tree: MdNode) => {
-    walkTree(tree, node => {
-      if (node.tagName !== 'code') {
-        return;
-      }
-
-      const properties = (node.properties || {}) as Record<string, unknown>;
-      if (!properties[SYNTHETIC_FRAGMENT]) {
-        return;
-      }
-
-      const first = boundaryText(node);
-      const last = boundaryText(node, true);
-      if (first?.value) {
-        first.value = first.value.replace(/^<>\r?\n/, '');
-      }
-      if (last?.value) {
-        last.value = last.value.replace(/\r?\n<\/>$/, '');
-      }
-
-      delete properties[SYNTHETIC_FRAGMENT];
-    });
-  };
+export interface ShisoMdxOptions extends MdxConfig {
+  /** Resolved docs.json `styling.codeBlocks`; defaults apply when omitted. */
+  codeBlocks?: ResolvedCodeBlockConfig;
 }
 
 function rehypeZoomableImages() {
@@ -142,7 +57,9 @@ function rehypeZoomableImages() {
  * The MDX compilation pipeline, shared by the app build and the test runner so
  * tests exercise the same transforms the site ships with.
  */
-export function shisoMdx(): Plugin {
+export function shisoMdx(options: ShisoMdxOptions = {}): Plugin {
+  const codeBlocks = options.codeBlocks || resolveCodeBlockConfig();
+
   return {
     // Must run before vite:react-babel so MDX is compiled to JSX first.
     enforce: 'pre',
@@ -152,13 +69,12 @@ export function shisoMdx(): Plugin {
         remarkFrontmatter,
         remarkMdxFrontmatter,
         remarkGfm,
-        remarkCodeTitles,
+        ...(options.remarkPlugins || []),
         remarkToc,
       ],
       rehypePlugins: [
-        rehypeWrapJsxForHighlighting,
-        rehypeHighlight,
-        rehypeRemoveHighlightingFragments,
+        ...(options.rehypePlugins || []),
+        [rehypeShiki, codeBlocks],
         rehypeZoomableImages,
         rehypeSlug,
         [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {
@@ -72,6 +72,7 @@
     "@fontsource/jetbrains-mono": "^5.2.5",
     "@mdx-js/react": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
+    "@shikijs/transformers": "^4.4.3",
     "@tailwindcss/vite": "^4.3.3",
     "@vitejs/plugin-react": "^6.0.5",
     "ajv": "^8.20.0",
@@ -80,24 +81,24 @@
     "cmdk": "^1.1.1",
     "estree-util-value-to-estree": "^3.5.0",
     "github-slugger": "^2.0.0",
-    "highlight.js": "^11.11.1",
     "jiti": "^2.4.0",
     "lucide-react": "^1.28.0",
     "react-router": "^8.3.0",
     "rehype-autolink-headings": "^7.1.0",
-    "rehype-highlight": "^7.0.1",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
     "remark-mdx": "^3.1.1",
     "remark-mdx-frontmatter": "^5.2.0",
     "remark-parse": "^11.0.0",
+    "shiki": "^4.4.3",
     "simple-icons": "^16.28.0",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
     "unified": "^11.0.5",
-    "vite": "^8.2.0"
+    "vite": "^8.2.0",
+    "yaml": "^2.9.0"
   },
   "optionalDependencies": {
     "pagefind": "^1.4.0"

package/scripts/build-runtime.mjs

@@ -10,6 +10,7 @@ const outputRoot = path.join(packageRoot, 'dist');
 const projectModules = new Set([
   '@/generated/last-modified',
   '@/lib/icon-registry.generated',
+  '@/lib/openapi.generated',
   '@/lib/search-index.generated',
   'virtual:shiso-docs-config',
   'virtual:shiso-config',

package/scripts/check-content.mjs

@@ -0,0 +1,358 @@
+/**
+ * Validates the content graph behind docs.json.
+ *
+ * Schema validation proves the configuration has the right shape; this pass
+ * proves that its page references, routes, links, anchors, and local assets
+ * describe a site that can actually be navigated.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { headingText } from './lib/mdast.mjs';
+import {
+  loadOpenApiSpec,
+  normalizeOperationKey,
+  normalizeOperations,
+  operationAnchors,
+} from './lib/openapi.mjs';
+import { createSlugger } from './lib/slug.mjs';
+import { loadDocsConfig } from './load-docs-config.mjs';
+import { loadShisoConfig } from './load-shiso-config.mjs';
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+const PAGE_EXTENSIONS = ['.mdx', '.md'];
+const parser = unified().use(remarkParse).use(remarkMdx).use(remarkFrontmatter).use(remarkGfm);
+
+function normalizePageReference(value) {
+  const fileSlug =
+    String(value || '')
+      .trim()
+      .replace(/\\/g, '/')
+      .replace(/^\/+/, '')
+      .replace(/^docs\//, '')
+      .replace(/\.mdx?$/i, '')
+      .replace(/\/+$/, '') || 'index';
+  const routeSlug = fileSlug === 'index' ? 'index' : fileSlug.replace(/\/index$/, '') || 'index';
+  return { fileSlug, routeSlug };
+}
+
+function normalizeRoute(value) {
+  const route = String(value || '/')
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/');
+  const withoutIndex = route === '/index' ? '/' : route.replace(/\/index$/, '') || '/';
+  return withoutIndex.length > 1 ? withoutIndex.replace(/\/+$/, '') : withoutIndex;
+}
+
+function pageRoute(routeSlug, docsPrefix) {
+  return normalizeRoute(routeSlug === 'index' ? docsPrefix || '/' : `${docsPrefix}/${routeSlug}`);
+}
+
+async function exists(filePath) {
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function listFiles(directory) {
+  const files = [];
+  let entries;
+
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    const item = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(item)));
+    } else if (entry.isFile()) {
+      files.push(item);
+    }
+  }
+
+  return files;
+}
+
+function collectPageReferences(navigation) {
+  const references = [];
+
+  function visitContainer(container) {
+    if (!container || typeof container !== 'object') return;
+    if (Array.isArray(container.pages)) visitItems(container.pages);
+    for (const key of ['tabs', 'dropdowns', 'groups', 'versions', 'languages']) {
+      if (Array.isArray(container[key])) container[key].forEach(visitContainer);
+    }
+  }
+
+  function visitItems(items) {
+    for (const item of items) {
+      if (typeof item === 'string') {
+        references.push(item);
+      } else if (item && typeof item === 'object') {
+        if (typeof item.page === 'string') references.push(item.page);
+        if (typeof item.root === 'string') references.push(item.root);
+        if (Array.isArray(item.pages)) visitItems(item.pages);
+      }
+    }
+  }
+
+  visitContainer(navigation);
+  return references;
+}
+
+async function resolveFile(root, directory, slug, extensions) {
+  for (const extension of extensions) {
+    const candidate = path.resolve(root, directory, `${slug}${extension}`);
+    if (await exists(candidate)) return candidate;
+  }
+  return null;
+}
+
+function walk(node, visitor) {
+  visitor(node);
+  for (const child of node.children || []) walk(child, visitor);
+}
+
+function literalAttribute(node, name) {
+  const attribute = (node.attributes || []).find(item => item?.name === name);
+  return typeof attribute?.value === 'string' ? attribute.value : null;
+}
+
+function inspectMarkdown(source, filePath) {
+  const tree = parser.parse(source);
+  const slugger = createSlugger();
+  const anchors = new Set();
+  const targets = [];
+
+  walk(tree, node => {
+    if (node.type === 'heading') anchors.add(slugger.slug(headingText(node)));
+
+    if (node.type === 'link' && typeof node.url === 'string') {
+      targets.push({ kind: 'link', value: node.url, line: node.position?.start.line || 1 });
+    } else if (node.type === 'image' && typeof node.url === 'string') {
+      targets.push({ kind: 'asset', value: node.url, line: node.position?.start.line || 1 });
+    } else if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+      const href = literalAttribute(node, 'href');
+      const src = literalAttribute(node, 'src');
+      if (href) targets.push({ kind: 'link', value: href, line: node.position?.start.line || 1 });
+      if (src) targets.push({ kind: 'asset', value: src, line: node.position?.start.line || 1 });
+    }
+  });
+
+  const frontmatter = source.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] || '';
+  return {
+    filePath,
+    anchors,
+    targets,
+    title: /^title\s*:/m.test(frontmatter),
+    description: /^description\s*:/m.test(frontmatter),
+    openapi: frontmatter.match(/^openapi:\s*(.+)$/m)?.[1]?.trim(),
+  };
+}
+
+function diagnostic(relativePath, line, message) {
+  return `${relativePath.replace(/\\/g, '/')}:${line} ${message}`;
+}
+
+function splitTarget(raw) {
+  const value = raw.trim();
+  const hashIndex = value.indexOf('#');
+  const beforeHash = hashIndex >= 0 ? value.slice(0, hashIndex) : value;
+  return {
+    pathname: beforeHash.split('?')[0],
+    fragment: hashIndex >= 0 ? value.slice(hashIndex + 1) : '',
+  };
+}
+
+function isExternal(value) {
+  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(value);
+}
+
+function resolveLinkRoute(rawPath, currentRoute) {
+  if (!rawPath) return currentRoute;
+  const value = rawPath.replace(/\.mdx?$/i, '');
+  if (value.startsWith('/')) return normalizeRoute(value);
+  return normalizeRoute(new URL(value, `https://shiso.invalid${currentRoute}`).pathname);
+}
+
+/** Returns content errors and non-fatal authoring warnings for one project. */
+export async function checkContent({ root = process.cwd(), config, shiso } = {}) {
+  const projectRoot = path.resolve(root);
+  const docsConfig = config ?? (await loadDocsConfig({ root: projectRoot })).config;
+  const engine = shiso ?? (await loadShisoConfig({ root: projectRoot })).config;
+  const errors = [];
+  const warnings = [];
+  const routes = new Map();
+  const pages = [];
+  const referencedFiles = new Set();
+
+  for (const reference of collectPageReferences(docsConfig.navigation)) {
+    const { fileSlug, routeSlug } = normalizePageReference(reference);
+    const filePath = await resolveFile(projectRoot, engine.contentDir, fileSlug, PAGE_EXTENSIONS);
+    const route = pageRoute(routeSlug, engine.docsPrefix);
+
+    if (!filePath) {
+      errors.push(
+        `docs.json references missing page "${fileSlug}" (expected ${engine.contentDir}/${fileSlug}.mdx or .md).`,
+      );
+      continue;
+    }
+
+    const previous = routes.get(route);
+    if (previous && previous !== filePath) {
+      errors.push(
+        `Route "${route}" is produced by both "${path.relative(projectRoot, previous)}" and "${path.relative(projectRoot, filePath)}".`,
+      );
+      continue;
+    }
+    if (referencedFiles.has(filePath)) {
+      errors.push(`Page "${fileSlug}" is referenced more than once in navigation.`);
+      continue;
+    }
+
+    routes.set(route, filePath);
+    referencedFiles.add(filePath);
+    pages.push({ route, filePath });
+  }
+
+  for (const item of docsConfig.pages || []) {
+    const route = normalizeRoute(item?.path);
+    const slug =
+      String(item?.page || 'index')
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/^\/+|\/+$/g, '')
+        .replace(/^pages\//, '')
+        .replace(/\.(?:mdx?|tsx)$/i, '') || 'index';
+    const filePath = await resolveFile(projectRoot, 'content/pages', slug, ['.tsx', '.mdx', '.md']);
+
+    if (!filePath) {
+      errors.push(
+        `docs.json references missing standalone page "${slug}" (expected content/pages/${slug}.tsx, .mdx, or .md).`,
+      );
+      continue;
+    }
+    if (routes.has(route)) {
+      errors.push(
+        `Standalone route "${route}" collides with "${path.relative(projectRoot, routes.get(route))}".`,
+      );
+      continue;
+    }
+    routes.set(route, filePath);
+    referencedFiles.add(filePath);
+    if (MARKDOWN_EXTENSIONS.has(path.extname(filePath))) pages.push({ route, filePath });
+  }
+
+  // Generated OpenAPI sections render at runtime, so their anchors come from
+  // the spec rather than from markdown headings.
+  let openApiByKey;
+  if (docsConfig.api?.spec) {
+    const { spec } = await loadOpenApiSpec({ root: projectRoot, specPath: docsConfig.api.spec });
+    openApiByKey = new Map(normalizeOperations(spec).map(operation => [operation.key, operation]));
+  }
+
+  const documents = new Map();
+  for (const page of pages) {
+    const source = await fs.readFile(page.filePath, 'utf8');
+    const document = inspectMarkdown(source, page.filePath);
+    const operationKey = normalizeOperationKey(document.openapi);
+    const operation = operationKey ? openApiByKey?.get(operationKey) : undefined;
+    if (operation) {
+      for (const anchor of operationAnchors(operation)) {
+        document.anchors.add(anchor);
+      }
+    }
+    documents.set(page.filePath, document);
+    const relative = path.relative(projectRoot, page.filePath).replace(/\\/g, '/');
+    if (!document.title) warnings.push(`${relative} has no frontmatter title.`);
+    if (!document.description) warnings.push(`${relative} has no frontmatter description.`);
+  }
+
+  const publicRoot = path.resolve(projectRoot, 'public');
+  for (const page of pages) {
+    const document = documents.get(page.filePath);
+    const relative = path.relative(projectRoot, page.filePath);
+
+    for (const target of document.targets) {
+      if (!target.value || isExternal(target.value)) continue;
+      const { pathname, fragment } = splitTarget(target.value);
+
+      if (target.kind === 'asset') {
+        const assetPath = pathname.startsWith('/')
+          ? path.resolve(publicRoot, pathname.replace(/^\/+/, ''))
+          : path.resolve(path.dirname(page.filePath), pathname);
+        if (!(await exists(assetPath))) {
+          errors.push(
+            diagnostic(relative, target.line, `references missing asset "${target.value}".`),
+          );
+        }
+        continue;
+      }
+
+      const targetRoute = resolveLinkRoute(pathname, page.route);
+      const targetFile = routes.get(targetRoute);
+
+      if (!targetFile && pathname && /\.[a-z\d]+$/i.test(pathname) && !/\.mdx?$/i.test(pathname)) {
+        const publicFile = pathname.startsWith('/')
+          ? path.resolve(publicRoot, pathname.replace(/^\/+/, ''))
+          : path.resolve(path.dirname(page.filePath), pathname);
+        if (await exists(publicFile)) continue;
+      }
+
+      if (!targetFile) {
+        errors.push(diagnostic(relative, target.line, `links to unknown route "${target.value}".`));
+        continue;
+      }
+
+      if (fragment && MARKDOWN_EXTENSIONS.has(path.extname(targetFile))) {
+        const targetDocument = documents.get(targetFile);
+        let decoded = fragment;
+        try {
+          decoded = decodeURIComponent(fragment);
+        } catch {
+          // Report the original fragment below.
+        }
+        if (targetDocument && !targetDocument.anchors.has(decoded)) {
+          errors.push(
+            diagnostic(
+              relative,
+              target.line,
+              `links to missing anchor "#${fragment}" on "${targetRoute}".`,
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  for (const redirect of docsConfig.redirects || []) {
+    if (
+      !isExternal(redirect.destination) &&
+      !routes.has(normalizeRoute(splitTarget(redirect.destination).pathname))
+    ) {
+      errors.push(
+        `Redirect "${redirect.source}" points to unknown route "${redirect.destination}".`,
+      );
+    }
+  }
+
+  const docsRoot = path.resolve(projectRoot, engine.contentDir);
+  for (const filePath of await listFiles(docsRoot)) {
+    if (MARKDOWN_EXTENSIONS.has(path.extname(filePath)) && !referencedFiles.has(filePath)) {
+      warnings.push(
+        `${path.relative(projectRoot, filePath).replace(/\\/g, '/')} is not referenced by navigation.`,
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}