@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/preview.d.ts

@@ -7,16 +7,40 @@ interface PreviewOptions {
     open: boolean;
 }
 export declare function startPreview(options: PreviewOptions): Promise<void>;
+/**
+ * A stored redirect is followed only when its target is a page the site can
+ * serve. Redirects are written when a plan is approved, before the pages are
+ * authored, so a target may name a planned path the author never used; falling
+ * through to the normal page lookup beats sending readers to "Page not found".
+ */
+export declare function redirectTarget(redirect: string | undefined, site: DoxbrixSiteConfig, pages: Map<string, string>): string | undefined;
 export declare function doxbrixDocument(input: {
     site: DoxbrixSiteConfig;
     title: string;
     description?: string;
+    canonical?: string;
+    socialImage?: string;
     current: string;
+    docVersion?: string;
     rendered: {
         html: string;
         toc: TocEntry[];
     };
+    verification?: {
+        state: string;
+        verifiedOn?: string;
+        revisions: Record<string, string>;
+        locale: string;
+    };
+    editorUrl?: string;
+    embedded?: boolean;
+    workspace?: boolean;
+    /** URL prefix used by static exports hosted below an origin, such as GitHub project pages. */
+    basePath?: string;
+    /** Static builds have no preview event stream. */
+    liveReload?: boolean;
 }): string;
+export declare function firstSitePage(site: DoxbrixSiteConfig): string | undefined;
 export declare function previewErrorPage(error: unknown): string;
 export {};
 //# sourceMappingURL=preview.d.ts.map

package/dist/preview.js

@@ -1,3 +1,4 @@
+import { readRedirects } from './page-operations.js';
 import { spawn } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
@@ -5,9 +6,12 @@ import { extname, isAbsolute, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chokidar from 'chokidar';
 import { renderMarkdown } from './doxbrix-markdown.js';
+import { DoxloopError } from './errors.js';
 import { resolveContainedDirectory } from './fs.js';
+import { loadQualityConfig } from './quality-config.js';
+import { reverifyClaims } from './quality-claims.js';
 import { loadGeneratorAdapter } from './generators.js';
-import { loadPages, loadProject, loadSiteConfig, pageId, readPage, siteConfigPath, } from './project.js';
+import { loadPages, loadProject, loadSiteConfig, pageId, readPage, ROOT_CONTENT_IGNORED_DIRECTORIES, siteConfigPath, } from './project.js';
 const PACKAGE_ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)));
 const DOXBRIX_CSS = resolve(PACKAGE_ROOT, 'assets', 'doxbrix-preview.css');
 const ATLAS_LAYOUT = {
@@ -44,12 +48,19 @@ export async function startPreview(options) {
     await startDoxbrixPreview(options, project);
 }
 async function startDoxbrixPreview(options, project) {
-    const contentRoot = await resolveContainedDirectory(options.root, project.contentDir, 'Preview content directory');
+    const contentRoot = await resolveContainedDirectory(options.root, project.contentDir, 'Preview content directory', { allowRoot: project.generator === 'doxbrix' });
     const css = await readFile(DOXBRIX_CSS, 'utf8');
     const clients = new Set();
+    const ignoredDirectories = contentRoot === resolve(options.root)
+        ? ROOT_CONTENT_IGNORED_DIRECTORIES
+        : undefined;
     const server = createServer(async (request, response) => {
         try {
             const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
+            if (url.pathname === '/__doxloop/identity') {
+                send(response, 200, 'application/json; charset=utf-8', JSON.stringify({ root: resolve(options.root) }));
+                return;
+            }
             if (url.pathname === '/__doxloop/events') {
                 response.writeHead(200, {
                     'Content-Type': 'text/event-stream',
@@ -65,7 +76,7 @@ async function startDoxbrixPreview(options, project) {
                 send(response, 200, 'text/css; charset=utf-8', css);
                 return;
             }
-            const staticPath = safeStaticPath(contentRoot, url.pathname);
+            const staticPath = safeStaticPath(contentRoot, url.pathname, ignoredDirectories);
             if (staticPath && STATIC_TYPES[extname(staticPath).toLowerCase()]) {
                 try {
                     send(response, 200, STATIC_TYPES[extname(staticPath).toLowerCase()], await readFile(staticPath));
@@ -75,11 +86,19 @@ async function startDoxbrixPreview(options, project) {
                     // A missing static asset may still be an extension-bearing documentation route.
                 }
             }
-            const [pages, site] = await Promise.all([
+            const [pages, site, qualityConfig, verificationMetadata] = await Promise.all([
                 loadPages(options.root, project),
                 loadSiteConfig(options.root, project),
+                loadQualityConfig(options.root),
+                loadQualityConfig(options.root).then((config) => config.readerVerification?.enabled ? reverifyClaims(options.root, project, false).then((result) => result.metadata) : undefined),
             ]);
             const pagesById = new Map(pages.map((path) => [pageId(contentRoot, path), path]));
+            const redirect = redirectTarget((await readRedirects(options.root))[url.pathname.replace(/\/$/, '') || '/'], site, pagesById);
+            if (redirect) {
+                response.writeHead(302, { Location: redirect });
+                response.end();
+                return;
+            }
             if (url.pathname === '/__doxloop/search-index') {
                 const entries = await Promise.all([...pagesById].map(async ([id, path]) => {
                     const page = await readPage(path);
@@ -104,8 +123,17 @@ async function startDoxbrixPreview(options, project) {
                 site,
                 title: page.title || labelFromId(requested),
                 ...(page.description ? { description: page.description } : {}),
+                ...(page.canonical ? { canonical: page.canonical } : {}),
+                ...(page.socialImage ? { socialImage: page.socialImage } : {}),
                 current: requested,
+                ...(url.searchParams.get('version') ? { docVersion: url.searchParams.get('version') } : {}),
+                ...(localEditorUrl(process.env.DOXLOOP_CONTROL_CENTER_URL, relative(options.root, pagesById.get(requested))) ? { editorUrl: localEditorUrl(process.env.DOXLOOP_CONTROL_CENTER_URL, relative(options.root, pagesById.get(requested))) } : {}),
                 rendered,
+                ...(url.searchParams.get('embed') === 'page' ? { embedded: true } : {}),
+                ...(url.searchParams.get('workspace') === '1' ? { workspace: true } : {}),
+                ...(qualityConfig.readerVerification?.enabled && verificationMetadata?.pages[relative(options.root, pagesById.get(requested)).replace(/\\/g, '/')]
+                    ? { verification: verificationMetadata.pages[relative(options.root, pagesById.get(requested)).replace(/\\/g, '/')] }
+                    : {}),
             }));
         }
         catch (error) {
@@ -121,7 +149,12 @@ async function startDoxbrixPreview(options, project) {
     if (options.open)
         openBrowser(url);
     const configPath = await siteConfigPath(options.root, project);
-    const watcher = chokidar.watch([contentRoot, configPath], { ignoreInitial: true });
+    const watcher = chokidar.watch([contentRoot, configPath], {
+        ignoreInitial: true,
+        ...(ignoredDirectories
+            ? { ignored: (path) => isIgnoredDirectoryPath(contentRoot, path, ignoredDirectories) }
+            : {}),
+    });
     watcher.on('all', () => {
         for (const client of clients)
             client.write('event: reload\ndata: now\n\n');
@@ -139,16 +172,40 @@ async function startDoxbrixPreview(options, project) {
     process.once('SIGINT', () => void stop());
     process.once('SIGTERM', () => void stop());
 }
+/**
+ * A stored redirect is followed only when its target is a page the site can
+ * serve. Redirects are written when a plan is approved, before the pages are
+ * authored, so a target may name a planned path the author never used; falling
+ * through to the normal page lookup beats sending readers to "Page not found".
+ */
+export function redirectTarget(redirect, site, pages) {
+    if (!redirect)
+        return undefined;
+    const target = requestedPage(redirect, site, pages);
+    return target !== undefined && pages.has(target) ? redirect : undefined;
+}
 function requestedPage(pathname, site, pages) {
     if (pathname === '/' || pathname === '') {
         return firstSitePage(site) ?? pages.keys().next().value;
     }
-    return decodeURIComponent(pathname.replace(/^\/+|\/+$/g, '')).replace(/\.(md|mdx)$/i, '');
+    const id = decodeURIComponent(pathname.replace(/^\/+|\/+$/g, '')).replace(/\.(md|mdx)$/i, '');
+    return pages.has(id) ? id : pages.has(`${id}/index`) ? `${id}/index` : id;
 }
 export function doxbrixDocument(input) {
-    const visibleSpaces = input.site.spaces.filter((space) => hasVisibleNavigation(space.nav));
+    const versions = input.site.versions ?? [];
+    const defaultVersion = defaultDocVersion(input.site);
+    const contexts = (versions.length ? versions.map((entry) => entry.version) : [undefined]).map((version) => {
+        const spaces = input.site.spaces.filter((space) => (!versions.length || (space.version ?? defaultVersion) === version) && hasVisibleNavigation(space.nav));
+        return { version, spaces, matching: spaces.find((space) => containsPage(space.nav, input.current)) };
+    });
+    const context = contexts.find((entry) => entry.version === input.docVersion && entry.matching)
+        ?? contexts.find((entry) => entry.version === defaultVersion && entry.matching)
+        ?? contexts.find((entry) => entry.matching)
+        ?? contexts.find((entry) => entry.version === defaultVersion)
+        ?? contexts[0];
+    const visibleSpaces = context.spaces;
     const showTabs = visibleSpaces.length > 1;
-    const activeSpace = visibleSpaces.find((space) => containsPage(space.nav, input.current)) ??
+    const activeSpace = context.matching ??
         visibleSpaces[0];
     const primary = themeColor(input.site, 'primaryColor', '#6366f1');
     const primaryLight = themeColor(input.site, 'lightColor', primary);
@@ -174,14 +231,14 @@ export function doxbrixDocument(input) {
         themeString(input.site, 'favicon', '') ||
         themeString(input.site, 'faviconDark', '');
     const siteName = input.site.name?.trim() || 'Documentation';
-    const tabs = visibleSpaces
+    const tabsFor = (entry) => entry.spaces
         .map((space) => {
         const first = firstPage(space.nav);
-        const active = space === activeSpace ? ' active' : '';
+        const active = space === (entry.matching ?? entry.spaces[0]) ? ' active' : '';
         const tabIcon = typeof space.icon === 'string' && space.icon.trim()
             ? space.icon
             : spaceIcon(space.name);
-        const tabTag = typeof space.tag === 'string' && space.tag
+        const tabTag = space.tag
             ? `<span class="dxb-atlas-tab-tag">${escapeHtml(space.tag)}</span>`
             : '';
         const label = `<span class="dxb-atlas-tab-icon">${brandIcon(tabIcon, 16)}</span><span>${escapeHtml(space.name)}</span>${tabTag}`;
@@ -190,11 +247,16 @@ export function doxbrixDocument(input) {
             : `<span class="dxb-atlas-tab${active}">${label}</span>`;
     })
         .join('');
-    const first = firstSitePage(input.site) ?? '';
+    const first = firstPageInVersion(input.site, context.version) ?? firstSitePage(input.site) ?? '';
     const logoHref = safeHref(themeString(input.site, 'logoHref', `/${first}`), `/${first}`);
-    const leftnav = activeSpace
-        ? `<aside class="dp-leftnav"><div class="dp-nav-tree">${navTree(activeSpace.nav, input.current)}</div></aside>`
-        : '';
+    const leftnav = contexts.map((entry) => {
+        const space = entry.matching ?? entry.spaces[0];
+        if (!space)
+            return '';
+        const attrs = versions.length ? ` data-doc-version="${escapeAttr(entry.version)}" data-current-version-page="${Boolean(entry.matching)}" data-version-eyebrow="${escapeAttr(groupContainingPage(space.nav, input.current) ?? '')}"` : '';
+        return `<aside class="dp-leftnav" aria-label="Documentation navigation"${attrs}${entry !== context ? ' hidden' : ''}>${versionSwitcher(input.site, entry.version)}<div class="dp-nav-tree">${navTree(space.nav, input.current)}</div></aside>`;
+    }).join('');
+    const tabs = contexts.filter((entry) => entry.spaces.length > 1).map((entry) => `<div class="dxb-atlas-tabs-bar"${versions.length ? ` data-doc-version="${escapeAttr(entry.version)}"` : ''}${entry !== context ? ' hidden' : ''}><nav class="dxb-atlas-tabs" aria-label="Documentation spaces">${tabsFor(entry)}</nav></div>`).join('');
     const toc = tocHtml(input.rendered.toc);
     const groupLabel = activeSpace
         ? groupContainingPage(activeSpace.nav, input.current)
@@ -204,6 +266,11 @@ export function doxbrixDocument(input) {
     const faviconLink = favicon
         ? `<link rel="icon" href="${escapeAttr(favicon)}">`
         : '';
+    const metadata = [
+        input.description ? `<meta name="description" content="${escapeAttr(input.description)}">` : '',
+        input.canonical ? `<link rel="canonical" href="${escapeAttr(input.canonical)}">` : '',
+        input.socialImage ? `<meta property="og:image" content="${escapeAttr(input.socialImage)}">` : '',
+    ].filter(Boolean).join('\n  ');
     const logo = logoLight || logoDark
         ? `<span class="dp-topnav-logo-img-wrap">${logoLight ? `<img class="dp-topnav-logo-img dp-topnav-logo-img--light${logoDark ? ' has-dark' : ''}" src="${escapeAttr(logoLight)}" alt="${escapeAttr(siteName)}">` : ''}${logoDark ? `<img class="dp-topnav-logo-img dp-topnav-logo-img--dark${logoLight ? ' has-light' : ''}" src="${escapeAttr(logoDark)}" alt="${escapeAttr(siteName)}">` : ''}</span>`
         : `<span class="dp-topnav-logo-mark" aria-hidden="true">${icon('book', 16)}</span><span class="dp-topnav-logo-text">${escapeHtml(siteName)}</span>`;
@@ -213,12 +280,14 @@ export function doxbrixDocument(input) {
     const eyebrow = groupLabel
         ? `<div class="dxb-atlas-eyebrow">${escapeHtml(groupLabel)}</div>`
         : '';
-    return `<!doctype html>
+    const verification = input.verification ? verificationBadge(input.verification) : '';
+    const document = `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(input.title)} · ${escapeHtml(siteName)}</title>
+  ${metadata}
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   ${fontStylesheet}
@@ -227,6 +296,7 @@ export function doxbrixDocument(input) {
   <style>
     ${fontFaces}
     body{margin:0}.dp-tab-panel{display:none}.dp-tab-panel.active{display:block}
+    .dxb-verification{display:inline-flex;align-items:center;gap:8px;margin-top:12px;padding:6px 9px;border:1px solid #cbd5e1;border-radius:999px;font-size:12px;color:#475569;background:#f8fafc}.dxb-verification strong{font-size:12px}.dxb-verification--verified{border-color:#99e1cb;color:#08745d;background:#effcf8}.dxb-verification--contradicted,.dxb-verification--needs-human{border-color:#fecaca;color:#a61b29;background:#fff5f5}
     .dp-nav-chevron{transition:transform .15s}.dp-nav-chevron:not(.open){transform:rotate(-90deg)}
     .dp-root--published{--project-primary:${escapeAttr(primary)};--project-primary-hover:${escapeAttr(primary)};
       --project-primary-rgb:${hexToRgb(primary)};--primary:${escapeAttr(primary)};--primary-rgb:${hexToRgb(primary)};
@@ -243,7 +313,7 @@ export function doxbrixDocument(input) {
   </style>
 </head>
 <body>
-<div class="dp-root dp-root--published" data-color-theme="${resolvedMode}" data-project-color-theme="${escapeAttr(mode)}" data-code-theme="${codeTheme}" data-shell-theme="atlas">
+<div class="dp-root dp-root--published${input.embedded ? ' dp-root--embedded' : ''}" data-color-theme="${resolvedMode}" data-project-color-theme="${escapeAttr(mode)}" data-code-theme="${codeTheme}" data-shell-theme="atlas">
   <header class="dxb-atlas-header">
     <div class="dxb-atlas-header-main"><div class="dxb-atlas-header-inner">
       <a class="dp-topnav-logo" href="${escapeAttr(logoHref)}">${logo}</a>
@@ -262,13 +332,13 @@ export function doxbrixDocument(input) {
         <button class="dp-theme-toggle" type="button" aria-label="Switch color theme" aria-pressed="${resolvedMode === 'dark'}" data-theme-toggle>${icon(resolvedMode === 'dark' ? 'sun' : 'moon', 17)}</button>
       </div>
     </div></div>
-    ${showTabs ? `<div class="dxb-atlas-tabs-bar"><nav class="dxb-atlas-tabs" aria-label="Documentation spaces">${tabs}</nav></div>` : ''}
+    ${tabs}
   </header>
   <div class="dp-body">
     ${leftnav}
-    <main class="dp-main"><div class="dp-content-wrap">
+    <main class="dp-main"><div class="dp-content-wrap">${input.editorUrl ? `<a class="dp-edit-page" href="${escapeHtml(input.editorUrl)}" target="_blank" rel="noopener">Edit this page in Doxloop</a>` : ''}
       <div class="dxb-atlas-title-row">
-        <div class="dxb-atlas-title-copy">${eyebrow}<h1 class="dp-page-title">${escapeHtml(input.title)}</h1>${description}</div>
+        <div class="dxb-atlas-title-copy">${eyebrow}<h1 class="dp-page-title">${escapeHtml(input.title)}</h1>${description}${verification}</div>
         <button class="dxb-atlas-copy-page" type="button" data-copy-page>${icon('copy', 16)}<span>Copy page</span>${icon('chevron-down', 14)}</button>
       </div>
       <div class="dp-blocks">${input.rendered.html}</div>
@@ -289,6 +359,14 @@ export function doxbrixDocument(input) {
   </div>
 </div>
 <script>
+  ${input.embedded && input.workspace ? `document.addEventListener('click', function(event) {
+    const link = event.target.closest('a[href]');
+    if (!link) return;
+    const target = new URL(link.href, location.href);
+    if (target.origin !== location.origin || (target.pathname === location.pathname && target.hash)) return;
+    event.preventDefault();
+    parent.postMessage({ type: 'doxloop:preview-navigate', href: target.href }, '*');
+  });` : ''}
   const root = document.querySelector('.dp-root--published');
   let colorTheme = root?.dataset.projectColorTheme || 'system';
   try {
@@ -346,8 +424,21 @@ export function doxbrixDocument(input) {
   updateActiveToc();
   addEventListener('scroll', scheduleTocUpdate, { passive: true });
   addEventListener('resize', scheduleTocUpdate);
-  const events = new EventSource('/__doxloop/events');
-  events.addEventListener('reload', () => location.reload());
+  ${input.liveReload === false ? 'const events = null;' : "const events = new EventSource('/__doxloop/events');"}
+  events?.addEventListener('reload', () => location.reload());
+  function closePreviewEvents() {
+    events?.close();
+  }
+  addEventListener('pagehide', closePreviewEvents, { once: true });
+  addEventListener('beforeunload', closePreviewEvents, { once: true });
+  document.addEventListener('click', (event) => {
+    const link = event.target instanceof Element ? event.target.closest('a[href]') : null;
+    if (!link || event.defaultPrevented || link.target === '_blank' || link.hasAttribute('download')) return;
+    const target = new URL(link.href, location.href);
+    const currentWithoutHash = location.origin + location.pathname + location.search;
+    const targetWithoutHash = target.origin + target.pathname + target.search;
+    if (target.origin === location.origin && targetWithoutHash !== currentWithoutHash) closePreviewEvents();
+  }, { capture: true });
   const previewNotice = document.querySelector('[data-preview-notice]');
   const previewAssistant = document.querySelector('[data-preview-assistant]');
   let previewNoticeTimer;
@@ -733,13 +824,70 @@ export function doxbrixDocument(input) {
       const active = searchResults?.querySelector('.dxb-preview-search-result.active');
       if (active) {
         event.preventDefault();
+        closePreviewEvents();
         location.href = active.href;
       }
     }
   });
 </script>
+${MERMAID_PREVIEW_SCRIPT}
+${versions.length ? versionContextScript(layout.tabsHeight) : ''}
 </body>
 </html>`;
+    return prefixStaticReferences(document, input.basePath);
+}
+/** Prefix root-relative reader URLs without touching external or fragment links. */
+function prefixStaticReferences(document, rawBasePath) {
+    if (rawBasePath === undefined)
+        return document;
+    const basePath = normalizeBasePath(rawBasePath);
+    if (!basePath)
+        return document;
+    return document
+        .replaceAll('href="/', `href="${basePath}/`)
+        .replaceAll('src="/', `src="${basePath}/`)
+        .replaceAll("fetch('/", `fetch('${basePath}/`)
+        .replaceAll("new EventSource('/", `new EventSource('${basePath}/`);
+}
+function normalizeBasePath(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === '/')
+        return '';
+    if (/^[a-z][a-z\d+.-]*:/i.test(trimmed) || trimmed.startsWith('//')) {
+        throw new DoxloopError('Static build base path must be an origin-relative URL path.');
+    }
+    const normalized = `/${trimmed.replace(/^\/+|\/+$/g, '')}`;
+    if (normalized.split('/').some((part) => part === '..')) {
+        throw new DoxloopError('Static build base path cannot leave its URL root.');
+    }
+    return normalized;
+}
+/**
+ * Render `<Mermaid>` blocks in the local preview. The published site renders
+ * diagrams itself; without this the preview showed the diagram source as
+ * plain text, so a concept page looked broken before it was ever published.
+ * Loaded only when a page contains a diagram, and a failed load (offline)
+ * leaves the readable source in place.
+ */
+const MERMAID_PREVIEW_SCRIPT = `<script type="module">
+  const diagrams = document.querySelectorAll('pre.mermaid');
+  if (diagrams.length > 0) {
+    try {
+      const { default: mermaid } = await import('https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs');
+      const dark = document.querySelector('.dp-root--published')?.dataset.colorTheme === 'dark';
+      mermaid.initialize({ startOnLoad: false, theme: dark ? 'dark' : 'neutral', securityLevel: 'strict' });
+      await mermaid.run({ nodes: diagrams });
+    } catch (error) {
+      console.warn('Doxloop preview could not render Mermaid diagrams; the published site renders them.', error);
+    }
+  }
+</script>`;
+function verificationBadge(verification) {
+    const label = verification.state === 'verified' ? 'Verified' : verification.state === 'inferred' ? 'Evidence inferred' : verification.state === 'contradicted' ? 'Contradicted — review required' : 'Needs review';
+    const revisions = Object.entries(verification.revisions).map(([source, revision]) => `${source} ${revision.slice(0, 12)}`).join(', ');
+    const date = verification.verifiedOn ? new Intl.DateTimeFormat(verification.locale, { dateStyle: 'medium', timeZone: 'UTC' }).format(new Date(verification.verifiedOn)) : '';
+    const detail = [date, revisions].filter(Boolean).join(' · ');
+    return `<aside class="dxb-verification dxb-verification--${escapeAttr(verification.state)}" aria-label="Documentation verification"><strong>${escapeHtml(label)}</strong>${detail ? `<span>${escapeHtml(detail)}</span>` : ''}</aside>`;
 }
 function navTree(nodes, current, depth = 0) {
     return nodes
@@ -755,9 +903,12 @@ function navTree(nodes, current, depth = 0) {
             return `<a class="dp-nav-item${depthClass(depth)}" href="${escapeAttr(safeNavigationHref(node.href))}">${navIcon(node.icon)}<span class="dp-nav-item-label">${escapeHtml(node.title)}</span></a>`;
         }
         if (node.type === 'api') {
-            return `<div class="dp-nav-item${depthClass(depth)}">${navIcon(node.icon)}<span class="dp-nav-item-label">${escapeHtml(node.title)}</span></div>`;
+            return `<a class="dp-nav-item${depthClass(depth)}" href="${escapeAttr(apiSpecHref(node.spec))}" target="_blank" rel="noreferrer">${navIcon(node.icon)}<span class="dp-nav-item-label">${escapeHtml(node.title)}</span></a>`;
         }
         if (node.type === 'group') {
+            // An empty header is nothing to click into; hide it rather than render a bare label.
+            if (!hasVisibleNavigation(node.items))
+                return '';
             const children = navTree(node.items, current, depth + 1);
             const activeBranch = containsPage(node.items, current) ? ' active-branch' : '';
             const groupIcon = navIcon(node.icon);
@@ -773,8 +924,8 @@ function navTree(nodes, current, depth = 0) {
 }
 function tocHtml(entries) {
     if (entries.length === 0)
-        return '<aside class="dp-toc"></aside>';
-    return `<aside class="dp-toc"><div class="dp-toc-header">${icon('list', 16)} On this page</div>${entries
+        return '<aside class="dp-toc" aria-label="On this page"></aside>';
+    return `<aside class="dp-toc" aria-label="On this page"><div class="dp-toc-header">${icon('list', 16)} On this page</div>${entries
         .map((entry, index) => `<a class="dp-toc-entry level-${entry.level}${index === 0 ? ' active' : ''}" href="#${escapeAttr(entry.id)}">${escapeHtml(entry.title)}</a>`)
         .join('')}</aside>`;
 }
@@ -804,7 +955,68 @@ function firstPage(nodes) {
     }
     return undefined;
 }
-function firstSitePage(site) {
+function defaultDocVersion(site) {
+    const versions = site.versions ?? [];
+    return (versions.find((entry) => entry.default === true || entry.isDefault === true) ?? versions[0])?.version;
+}
+function firstPageInVersion(site, version) {
+    for (const space of site.spaces) {
+        if (site.versions?.length && (space.version ?? defaultDocVersion(site)) !== version)
+            continue;
+        const first = firstPage(space.nav);
+        if (first)
+            return first;
+    }
+    return undefined;
+}
+// Mirrors the Doxbrix CLI reader: default/isDefault and a sidebar dropdown.
+function versionSwitcher(site, version) {
+    const versions = site.versions ?? [];
+    if (versions.length < 2)
+        return '';
+    const active = versions.find((entry) => entry.version === version) ?? versions[0];
+    const label = (entry) => `<span class="dp-version-label">${escapeHtml(entry.label ?? entry.version)}</span>${entry.tag ? `<span class="dp-version-tag">${escapeHtml(entry.tag)}</span>` : ''}`;
+    const options = versions.map((entry) => {
+        const first = firstPageInVersion(site, entry.version);
+        return first
+            ? `<a class="dp-version-option${entry === active ? ' active' : ''}" href="/${escapeAttr(first)}?version=${escapeAttr(encodeURIComponent(entry.version))}"${entry === active ? ' aria-current="true"' : ''}>${label(entry)}</a>`
+            : `<span class="dp-version-option" aria-disabled="true">${label(entry)}</span>`;
+    }).join('');
+    return `<details class="dp-version-switcher"><summary class="dp-version-trigger" aria-label="Documentation version: ${escapeAttr(active.label ?? active.version)}">${label(active)}${icon('chevron-down', 12)}</summary><nav class="dp-version-menu" aria-label="Documentation versions">${options}</nav></details>`;
+}
+function versionContextScript(tabsHeight) {
+    // Shared pages have one static HTML file. Keep the selected version in their URL
+    // and select the matching pre-rendered navigation for previews and static hosts.
+    return `<script>
+  (() => {
+    const sides = [...document.querySelectorAll('aside[data-doc-version]')];
+    const requested = new URL(location.href).searchParams.get('version');
+    const side = sides.find((entry) => entry.dataset.docVersion === requested && entry.dataset.currentVersionPage === 'true') || sides.find((entry) => !entry.hidden);
+    if (!side) return;
+    const version = side.dataset.docVersion;
+    document.querySelectorAll('[data-doc-version]').forEach((entry) => { entry.hidden = entry.dataset.docVersion !== version; });
+    const tabs = [...document.querySelectorAll('.dxb-atlas-tabs-bar')].find((entry) => !entry.hidden);
+    document.querySelector('.dp-root')?.style.setProperty('--dxb-tabs-height', tabs ? '${tabsHeight}px' : '0px');
+    const eyebrow = document.querySelector('.dxb-atlas-eyebrow');
+    if (eyebrow) eyebrow.textContent = side.dataset.versionEyebrow || '';
+    const logo = document.querySelector('.dp-topnav-logo');
+    const home = side.querySelector('.dp-version-option.active');
+    if (logo && home) logo.href = home.href;
+    const preserve = (link) => {
+      if (!link || link.closest('.dp-version-switcher') || !link.getAttribute('href') || link.getAttribute('href').startsWith('#')) return;
+      const url = new URL(link.href, location.href);
+      if (url.origin !== location.origin || /\\.[a-z0-9]+$/i.test(url.pathname) && !/\\.mdx?$/i.test(url.pathname)) return;
+      if (!url.searchParams.has('version')) { url.searchParams.set('version', version); link.href = url.href; }
+    };
+    document.querySelectorAll('a[href]').forEach(preserve);
+    document.addEventListener('click', (event) => preserve(event.target.closest('a[href]')), true);
+  })();
+  </script>`;
+}
+export function firstSitePage(site) {
+    const defaultFirst = firstPageInVersion(site, defaultDocVersion(site));
+    if (defaultFirst)
+        return defaultFirst;
     for (const space of site.spaces) {
         const first = firstPage(space.nav);
         if (first)
@@ -1014,7 +1226,9 @@ function googleFontStylesheet(families) {
         return '';
     const query = unique
         .slice(0, 3)
-        .map((family) => `family=${encodeURIComponent(family)}:wght@400;500;600;700;800`)
+        .map((family) => family.toLowerCase() === 'inter'
+        ? 'family=Inter:ital,wght@0,100..900;1,100..900'
+        : `family=${encodeURIComponent(family)}:wght@400;500;600;700;800`)
         .join('&');
     return `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?${query}&display=swap">`;
 }
@@ -1042,6 +1256,19 @@ function safeNavigationHref(value) {
     }
     return '#';
 }
+function apiSpecHref(value) {
+    const trimmed = value.trim();
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    if (trimmed === '' ||
+        trimmed.startsWith('//') ||
+        trimmed.includes('\\') ||
+        trimmed.split(/[/?#]/).includes('..')) {
+        return '#';
+    }
+    const local = trimmed.replace(/^\.\//, '');
+    return local.startsWith('/') ? local : `/${local}`;
+}
 function depthClass(depth) {
     return depth === 0 ? '' : ` dp-nav-d${Math.min(depth, 3)}`;
 }
@@ -1052,7 +1279,7 @@ function labelFromId(id) {
         .map((word) => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`)
         .join(' ');
 }
-function safeStaticPath(contentRoot, pathname) {
+function safeStaticPath(contentRoot, pathname, ignoredDirectories) {
     let decoded;
     try {
         decoded = decodeURIComponent(pathname);
@@ -1062,7 +1289,16 @@ function safeStaticPath(contentRoot, pathname) {
     }
     const path = resolve(contentRoot, decoded.replace(/^\/+/, ''));
     const rel = relative(contentRoot, path);
-    return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? undefined : path;
+    return rel === '' || rel.startsWith('..') || isAbsolute(rel)
+        || isIgnoredDirectoryPath(contentRoot, path, ignoredDirectories)
+        ? undefined
+        : path;
+}
+function isIgnoredDirectoryPath(contentRoot, path, ignoredDirectories) {
+    if (!ignoredDirectories)
+        return false;
+    const first = relative(contentRoot, path).split(/[\\/]/)[0];
+    return first !== undefined && ignoredDirectories.has(first);
 }
 function errorPage(requested, site) {
     return `<!doctype html><meta charset="utf-8"><title>Page not found</title><body style="font-family:system-ui;padding:40px"><h1>Page not found</h1><p>No Doxbrix page matches <code>/${escapeHtml(requested)}</code> in ${escapeHtml(site.name ?? 'this project')}.</p></body>`;
@@ -1146,4 +1382,19 @@ function openBrowser(url) {
     const child = spawn(command, args, { detached: true, stdio: 'ignore' });
     child.unref();
 }
+function localEditorUrl(origin, path) {
+    if (!origin)
+        return undefined;
+    try {
+        const url = new URL(origin);
+        if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(url.hostname) || url.username || url.password)
+            return undefined;
+        url.pathname = '/pages';
+        url.search = new URLSearchParams({ path: path.replace(/\\/g, '/'), edit: '1' }).toString();
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=preview.js.map

package/dist/project-detect.d.ts

@@ -0,0 +1,36 @@
+import type { GeneratorName } from './types.js';
+/**
+ * One way the folder could be read. `contentDir` is the directory Doxloop
+ * would treat as documentation content, relative to the folder; an empty
+ * string means the folder itself, which only Doxbrix allows.
+ */
+export interface GeneratorCandidate {
+    generator: GeneratorName;
+    contentDir: string;
+    markers: string[];
+    title?: string;
+}
+export interface GeneratorDetection {
+    /** Most specific marker first. Empty when nothing recognizable was found. */
+    candidates: GeneratorCandidate[];
+    recommended?: GeneratorCandidate;
+}
+/**
+ * Page extensions per generator when the adapter package cannot be loaded,
+ * so a folder can be inspected before anything is installed.
+ */
+export declare const DEFAULT_PAGE_EXTENSIONS: Record<GeneratorName, readonly string[]>;
+/**
+ * Recognize an existing documentation site from the files its generator
+ * needs. Detection only reads; it never writes into the folder. Order matters
+ * where markers overlap: a Docusaurus or MkDocs site may also carry a Jekyll
+ * style `_config.yml`, so the more specific generator is listed first.
+ */
+export declare function detectDocumentationGenerator(root: string): Promise<GeneratorDetection>;
+/**
+ * Project-relative page paths under a content directory, using the
+ * generator's default extensions. Missing directories yield no pages instead
+ * of an error so an inspection can report "0 pages" for a wrong guess.
+ */
+export declare function listDocumentationPageFiles(root: string, generator: GeneratorName, contentDir: string): Promise<string[]>;
+//# sourceMappingURL=project-detect.d.ts.map