@writedocs/generator 0.1.0

package/src/pages/[...slug].md.ts

@@ -0,0 +1,78 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { APIRoute } from 'astro';
+import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
+import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+
+// The raw-Markdown twin of [...slug].astro: every content page is also
+// reachable at the exact same slug with a literal ".md" suffix (e.g.
+// /guides/foo/ -> /guides/foo.md), serving its untouched MDX/Markdown
+// source instead of rendered HTML - what the "Copy page"/"View as
+// Markdown" menu (CopyPageMenu.astro, wired in from [...slug].astro)
+// links to, and what an LLM fetching that URL directly gets. Gated
+// entirely behind writedocs.json's `contextMenu` field being present (see
+// contextMenuSchema in lib/config.ts) - a site that hasn't opted in gets
+// no .md routes at all, not just a hidden menu.
+//
+// A literal ".md" filename suffix rather than a `[...slug]` capture
+// covering it: naming the file `[...slug].md.ts` makes Astro treat ".md"
+// as a static part of the route, not part of the `...slug` rest
+// parameter - requesting /guides/foo.md resolves with `slug ===
+// "guides/foo"`, exactly like the HTML router's own `entry.id`-derived
+// slug, just without the trailing-slash convention HTML pages use.
+//
+// getStaticPaths here is intentionally self-contained rather than
+// sharing a module-level helper with [...slug].astro's own
+// getStaticPaths - see that file's own extensive comment on Astro's
+// getStaticPaths bundling extraction silently dropping top-level
+// helper functions that are only referenced from inside it.
+type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
+
+export async function getStaticPaths() {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  const config = loadDocsConfig(contentDir);
+  // No writedocs.json `contextMenu` - feature is off entirely, including these
+  // routes (not just the menu UI - see the file-level comment above).
+  if (!config.contextMenu) return [];
+
+  const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
+  const hasPages = findAllPages(contentDir).length > 0;
+  const [pagesEntries, generatedDocsEntries] = await Promise.all([
+    hasPages ? getCollection('pages') : Promise.resolve([]),
+    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
+  ]);
+  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
+
+  return entries
+    // OpenAPI operation pages (generated stubs, or hand-written pages that
+    // set `openapi:` frontmatter) render almost entirely from the spec at
+    // request time (see ApiPlayground.astro) rather than from prose in
+    // entry.body - a raw .md dump of one would be near-empty and useless
+    // as an LLM-facing "view this page as text" export, so they're left
+    // out of this route entirely rather than serving something misleading.
+    .filter((entry) => !entry.data.openapi)
+    .map((entry) => ({
+      params: { slug: normalizeEntryId(entry.id) },
+      props: { entry },
+    }));
+}
+
+interface Props {
+  entry: DocsEntry;
+}
+
+export const GET: APIRoute = ({ props }) => {
+  const { entry } = props as Props;
+  // entry.body is the raw, frontmatter-stripped MDX/Markdown source text
+  // Astro's glob() loader already read off disk and stashed on every
+  // entry by default (see astro/dist/content/loaders/glob.js) - reusing
+  // it here means this route needs no separate file read/parse of its
+  // own, and always matches exactly what [...slug].astro rendered from
+  // (same entry, same collection query).
+  const body = entry.body ?? '';
+  const markdown = `# ${entry.data.title}\n\n${body}`;
+  return new Response(markdown, {
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+  });
+};

package/src/pages/llms-full.txt.ts

@@ -0,0 +1,71 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { APIRoute } from 'astro';
+import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
+import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+
+// The "everything, concatenated" half of the llms.txt pair - see
+// llms.txt.ts (right next to this file) for the lightweight index half,
+// and that file's own top-of-file comment for the shared design notes
+// (fixed non-dynamic route, unconditional/always generated, custom
+// project-root override file support).
+//
+// Unlike llms.txt.ts, there's no `contextMenu`-dependent branch here:
+// this route doesn't link to anything, it *is* the raw content, sourced
+// the same way [...slug].md.ts sources a single page's raw content
+// (`entry.body`, already read off disk by the glob() loader - no
+// separate file read needed).
+type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
+
+export const GET: APIRoute = async () => {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+
+  const customPath = path.join(contentDir, 'llms-full.txt');
+  if (fs.existsSync(customPath)) {
+    return new Response(fs.readFileSync(customPath, 'utf-8'), {
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+
+  const config = loadDocsConfig(contentDir);
+
+  const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
+  const hasPages = findAllPages(contentDir).length > 0;
+  const [pagesEntries, generatedDocsEntries] = await Promise.all([
+    hasPages ? getCollection('pages') : Promise.resolve([]),
+    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
+  ]);
+  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
+
+  const sections = entries
+    // Same exclusion [...slug].md.ts applies to its own per-page raw
+    // Markdown route, for the same reason: an OpenAPI operation page
+    // (generated stub, or a hand-written page that opts into rendering
+    // <ApiPlayground /> via `openapi:` frontmatter) renders almost
+    // entirely from the spec at request time, so entry.body alone is
+    // near-empty and not a meaningful "full content" contribution here.
+    .filter((entry) => !entry.data.openapi)
+    // Same noindex exclusion llms.txt.ts applies to its own listing -
+    // see that file's comment.
+    .filter((entry) => !entry.data.seo?.noindex)
+    .map((entry: DocsEntry) => {
+      const slug = normalizeEntryId(entry.id);
+      const body = entry.body ?? '';
+      return { slug, title: entry.data.title, body };
+    })
+    .sort((a, b) => a.slug.localeCompare(b.slug));
+
+  const lines: string[] = [`# ${config.name}`, ''];
+  if (config.description) lines.push(`> ${config.description}`, '');
+
+  for (const section of sections) {
+    lines.push('---', '', `# ${section.title}`, '', section.body.trim(), '');
+  }
+
+  const content = lines.join('\n') + '\n';
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/src/pages/llms.txt.ts

@@ -0,0 +1,141 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { APIRoute } from 'astro';
+import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl } from '../lib/config';
+import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+
+// A lightweight, LLM-facing index of every page on the site - the
+// llms.txt convention (see https://llmstxt.org), also adopted by Mintlify
+// and others: a plain-text file at the project root listing every page
+// with a one-line description, so an AI tool can decide what's worth
+// fetching without downloading the whole site. This is the "index" half
+// of the pair; llms-full.txt (llms-full.txt.ts, right next to this file)
+// is the "everything, concatenated" half.
+//
+// Fixed, non-dynamic route (no getStaticPaths/params needed) - Astro
+// prerenders this once at the literal path /llms.txt, same as any other
+// static-output route (this project's astro.config.mjs sets
+// `output: 'static'`), and re-evaluates it per request in `writedocs dev`
+// - see [...slug].md.ts for the same fixed-route-vs-catchall distinction
+// applied to per-page raw Markdown.
+//
+// Unconditional - unlike the per-page .md routes in [...slug].md.ts,
+// this doesn't depend on writedocs.json's `contextMenu` field. There's no UI
+// footprint to gate (it's an extra static file, not a visible menu), so
+// it's always generated. `contextMenu` only affects which URL each entry
+// links to below (a real fetchable .md URL if the per-page raw-Markdown
+// routes exist, the ordinary HTML page URL otherwise).
+type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
+
+// Mirrors Mintlify's own llms.txt behavior: truncate a page's frontmatter
+// `description` at the first line break (a multi-paragraph description
+// would blow out a one-line list entry) and at 300 characters (an
+// arbitrary but reasonable cap - keeps every entry scannable regardless
+// of how verbose an individual page's description happens to be).
+const DESCRIPTION_MAX_CHARS = 300;
+function truncateDescription(description: string | undefined): string | undefined {
+  if (!description) return undefined;
+  const firstLine = description.split('\n')[0].trim();
+  if (!firstLine) return undefined;
+  return firstLine.length > DESCRIPTION_MAX_CHARS
+    ? firstLine.slice(0, DESCRIPTION_MAX_CHARS).trimEnd() + '…'
+    : firstLine;
+}
+
+// Same cap Mintlify documents for its own auto-generated llms.txt - this
+// file is meant to stay a lightweight index (one line per page), not
+// balloon into something llms-full.txt-sized. Realistically unlikely to
+// matter for most Writedocs sites (a site would need on the order of a
+// thousand-plus pages with full-length descriptions to hit this), but
+// cheap to guard against regardless.
+const MAX_CHARS = 100_000;
+
+export const GET: APIRoute = async () => {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+
+  // A hand-authored llms.txt at the project root (next to writedocs.json)
+  // always wins outright over the generated one below - same override
+  // convention Mintlify documents for its own llms.txt. Lets a site
+  // author hand-curate this file (different ordering, editorial
+  // descriptions, extra sections) without losing the ability to fall
+  // back to the auto-generated version by just deleting the override.
+  const customPath = path.join(contentDir, 'llms.txt');
+  if (fs.existsSync(customPath)) {
+    return new Response(fs.readFileSync(customPath, 'utf-8'), {
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+
+  const config = loadDocsConfig(contentDir);
+  const siteUrl = resolveSiteUrl(config); // absolute origin if `domain` is set, else null
+
+  const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
+  const hasPages = findAllPages(contentDir).length > 0;
+  const [pagesEntries, generatedDocsEntries] = await Promise.all([
+    hasPages ? getCollection('pages') : Promise.resolve([]),
+    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
+  ]);
+  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
+
+  const items = entries
+    // A page that opted out of search-engine indexing (frontmatter
+    // `seo.noindex: true`, already excluded from sitemap.xml - see
+    // astro.config.mjs's collectNoindexIds()) is excluded here for the
+    // same reason: llms.txt exists to help external tools discover
+    // pages, exactly what `noindex` asked not to happen.
+    .filter((entry) => !entry.data.seo?.noindex)
+    .map((entry: DocsEntry) => {
+      const slug = normalizeEntryId(entry.id);
+      // Same URL Astro's own router resolves this entry to - see
+      // hrefForSlug() in [...slug].astro for the HTML form, and
+      // [...slug].md.ts for the .md form (no trailing slash, "index.md"
+      // for the home page rather than the HTML convention's bare "/").
+      const path_ = config.contextMenu ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`;
+      const href = (siteUrl ?? '') + path_;
+      let description = truncateDescription(entry.data.description);
+      // Mirrors Mintlify's own behavior: an OpenAPI operation page's
+      // description gets its "METHOD /path" appended, since the page
+      // itself renders almost entirely from the spec at request time
+      // (see ApiPlayground.astro) rather than from frontmatter prose.
+      if (entry.data.openapi) {
+        description = description ? `${description} (${entry.data.openapi})` : entry.data.openapi;
+      }
+      return { title: entry.data.title, href, description, slug };
+    })
+    .sort((a, b) => a.slug.localeCompare(b.slug));
+
+  const lines: string[] = [`# ${config.name}`, ''];
+  if (config.description) lines.push(`> ${config.description}`, '');
+  lines.push('## Docs', '');
+  for (const item of items) {
+    const entryLine = `- [${item.title}](${item.href})${item.description ? `: ${item.description}` : ''}`;
+    lines.push(entryLine);
+  }
+
+  let content = lines.join('\n') + '\n';
+  if (content.length > MAX_CHARS) {
+    // Truncate at the last full line inside the budget, then note how
+    // many entries got cut - rather than silently producing a
+    // mid-sentence-cutoff file, or (worse) one JSON/Markdown-breaking
+    // half-written link.
+    const truncatedLines = lines.slice(0, 4 + (config.description ? 2 : 0)); // "# name" / "" / ["> desc" / ""] / "## Docs" / ""
+    let runningLength = truncatedLines.join('\n').length + 1;
+    let omitted = 0;
+    for (const item of items) {
+      const entryLine = `- [${item.title}](${item.href})${item.description ? `: ${item.description}` : ''}`;
+      if (runningLength + entryLine.length + 1 > MAX_CHARS - 200) {
+        omitted++;
+        continue;
+      }
+      truncatedLines.push(entryLine);
+      runningLength += entryLine.length + 1;
+    }
+    truncatedLines.push('', `_Truncated — ${omitted} more page(s) omitted. See llms-full.txt or the site's own navigation for the complete list._`);
+    content = truncatedLines.join('\n') + '\n';
+  }
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/src/scripts/banner.ts

@@ -0,0 +1,20 @@
+// writedocs.json's dismissible `banner` (bannerSchema in lib/config.ts) - pairs
+// with the [data-banner-dismissed] flash-prevention script in BaseLayout's
+// <head>, which is what actually hides the banner on repeat visits; this
+// only needs to persist the choice and hide it for the rest of the current
+// page view once clicked.
+export function initBanner(root: ParentNode) {
+  const btn = root.querySelector<HTMLButtonElement>('[data-banner-dismiss]');
+  if (!btn || btn.dataset.wdInit) return;
+  btn.dataset.wdInit = 'true';
+  btn.addEventListener('click', () => {
+    document.documentElement.dataset.bannerDismissed = 'true';
+    try {
+      localStorage.setItem('wd-banner-dismissed', 'true');
+    } catch (e) {
+      // localStorage unavailable - banner still hides for this page view
+      // via the [data-banner-dismissed] attribute set above, just won't
+      // persist across reloads.
+    }
+  });
+}

package/src/scripts/dropdowns.ts

@@ -0,0 +1,61 @@
+// Wires up every `.wd-dropdown` on the page: click-to-toggle, click-outside
+// and Escape to close, and (via plain CSS alongside this) hover-to-reveal.
+// Generic by design - not scoped to any one feature's markup. Originally
+// written for the topbar's own switcher/tab dropdowns, but the same
+// `.wd-dropdown`/`.wd-dropdown-trigger`/`.wd-dropdown-menu`/
+// `.wd-dropdown-menu-panel` shape is now reused by TopBar.astro (switchers,
+// tabs, the small-screen topbar.links ellipsis) and CopyPageMenu.astro, and
+// exported from here so any future component - MobileMenu.astro included,
+// even though it doesn't render any `.wd-dropdown` markup today - can import
+// and call it too without needing to know whether some other component
+// already has.
+//
+// That "might get called more than once per page" scenario is exactly why
+// the two `document`-level listeners at the bottom are behind their own
+// module-level guard, separate from the existing per-trigger
+// `dataset.wdInit` guard: querying `.wd-dropdown` from more than one
+// component's own `<script>` (each already idempotent per-trigger) would,
+// without this, still add a fresh pair of document click/keydown listeners
+// on every single call - harmless individually, but wasteful if it keeps
+// happening across repeated calls (e.g. once per component that imports
+// this, or once per `astro:page-load` firing from more than one place).
+let globalListenersBound = false;
+
+export function initDropdowns(root: ParentNode) {
+  const dropdowns = Array.from(root.querySelectorAll<HTMLElement>('.wd-dropdown'));
+  if (dropdowns.length === 0) return;
+
+  const closeAll = () => {
+    dropdowns.forEach((d) => {
+      d.classList.remove('open');
+      d.querySelector('.wd-dropdown-trigger')?.setAttribute('aria-expanded', 'false');
+    });
+  };
+
+  dropdowns.forEach((dropdown) => {
+    const trigger = dropdown.querySelector<HTMLButtonElement>('.wd-dropdown-trigger');
+    if (!trigger || trigger.dataset.wdInit) return;
+    trigger.dataset.wdInit = 'true';
+    trigger.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const isOpen = dropdown.classList.contains('open');
+      closeAll();
+      if (!isOpen) {
+        dropdown.classList.add('open');
+        trigger.setAttribute('aria-expanded', 'true');
+      }
+    });
+  });
+
+  if (!globalListenersBound) {
+    globalListenersBound = true;
+    // Bound once against `document`, not `root` - closeAll() above already
+    // closes every dropdown found on the page regardless of which root a
+    // given call was scoped to, so there's no reason for these two to be
+    // scoped any narrower or bound more than once.
+    document.addEventListener('click', closeAll);
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') closeAll();
+    });
+  }
+}

package/src/scripts/image-zoom.ts

@@ -0,0 +1,66 @@
+// Click-to-zoom lightbox for content images - opened by ImageZoom.astro's
+// own overlay markup, mounted once in BaseLayout.astro alongside
+// SearchModal. Every <img> inside .wd-article becomes clickable and opens
+// a fullscreen view of itself, *except*:
+//   - Card's own image (.wd-card-image) - a UI element of the card
+//     itself (its header art), not "content" a reader would want to
+//     inspect at full size.
+//   - Icon's own inline image (.wd-icon-image) - a small inline glyph
+//     sized in em to match surrounding text, not a photo/screenshot.
+//   - any image explicitly opted out via a `nozoom` attribute - written
+//     as `<img noZoom src="..." />` in source (Image.astro's own
+//     `noZoom` prop renders the same attribute - see its own comment),
+//     but HTML attribute names are ASCII-case-insensitive during
+//     parsing, so the DOM (and this selector) sees it as `nozoom`
+//     regardless of how it was cased in source.
+// Scoped to .wd-article (not a bare `img` selector) so this never
+// touches chrome images - the topbar/sidebar logo, sidebar icons, or
+// anything else outside actual page content.
+export function initImageZoom(root: ParentNode) {
+  const overlay = document.querySelector<HTMLElement>('#wd-zoom-overlay');
+  const overlayImg = document.querySelector<HTMLImageElement>('#wd-zoom-image');
+  if (!overlay || !overlayImg) return;
+
+  const images = root.querySelectorAll<HTMLImageElement>(
+    '.wd-article img:not(.wd-card-image):not(.wd-icon-image):not([nozoom])',
+  );
+  images.forEach((img) => {
+    if (img.dataset.wdInit) return;
+    img.dataset.wdInit = 'true';
+    img.classList.add('wd-zoomable');
+    img.addEventListener('click', () => open(img));
+  });
+
+  // The overlay itself only needs its own listeners bound once - re-running
+  // initImageZoom() on every astro:page-load (view transitions swap in a
+  // whole new set of <img> elements, but ImageZoom.astro's overlay markup
+  // is part of BaseLayout's own persistent chrome, not the swapped page
+  // content) would otherwise stack up duplicate close listeners.
+  if (overlay.dataset.wdInit) return;
+  overlay.dataset.wdInit = 'true';
+
+  function open(img: HTMLImageElement) {
+    if (!overlay || !overlayImg) return;
+    // currentSrc (not src) accounts for a <picture>/srcset-based image
+    // resolving to something other than its own plain `src` attribute -
+    // falls back to `src` for the common case where there's no srcset.
+    overlayImg.src = img.currentSrc || img.src;
+    overlayImg.alt = img.alt;
+    overlay.hidden = false;
+    document.body.style.overflow = 'hidden';
+  }
+  function close() {
+    if (!overlay || !overlayImg) return;
+    overlay.hidden = true;
+    document.body.style.overflow = '';
+    overlayImg.src = '';
+  }
+  // No target === overlay check (unlike SearchModal's own backdrop-click
+  // handling) - there's no separate interactive panel to protect here,
+  // the whole overlay (backdrop, image, close button) is meant to close
+  // on any click within it.
+  overlay.addEventListener('click', close);
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && !overlay.hidden) close();
+  });
+}

package/src/scripts/mobile-menu.ts

@@ -0,0 +1,55 @@
+// The <= 860px hamburger menu (MobileMenu.astro's own toggle button +
+// overlay panel). The accordion rows inside the panel need no JS of their
+// own - they're plain <details name="wd-mobile-accordion"> elements, which
+// get native click/keyboard toggling and (in browsers supporting the
+// `name` attribute's exclusive-accordion behavior) mutual exclusion for
+// free, same as NavTree.astro's own collapsible groups already rely on
+// <details> for. This function only owns the panel itself: open/close, the
+// backdrop, Escape, and body scroll locking while it's open - same pattern
+// initSearch() uses for its own modal.
+export function initMobileMenu(root: ParentNode) {
+  const trigger = root.querySelector<HTMLButtonElement>('[data-mobile-menu-trigger]');
+  const menu = root.querySelector<HTMLElement>('#wd-mobile-menu');
+  const backdrop = menu?.querySelector<HTMLElement>('[data-mobile-menu-backdrop]');
+  // The panel's own close button (.wd-mobile-menu-header, next to its
+  // replica of the topbar brand) - the real hamburger-turned-X trigger up
+  // in the topbar is covered by the panel itself once open, so this is the
+  // only reachable way to close via click besides the backdrop.
+  const closeBtn = menu?.querySelector<HTMLButtonElement>('[data-mobile-menu-close]');
+  if (!trigger || !menu || !backdrop || trigger.dataset.wdInit) return;
+  trigger.dataset.wdInit = 'true';
+
+  function open() {
+    menu!.classList.add('open');
+    // `inert` (not just visibility/pointer-events, which only affect
+    // vision/mouse) is what keeps the closed panel's links out of Tab
+    // order and off a screen reader's radar - removed while open so its
+    // content becomes reachable again.
+    menu!.removeAttribute('inert');
+    trigger!.classList.add('open');
+    trigger!.setAttribute('aria-expanded', 'true');
+    document.body.style.overflow = 'hidden';
+  }
+  function close() {
+    menu!.classList.remove('open');
+    menu!.setAttribute('inert', '');
+    trigger!.classList.remove('open');
+    trigger!.setAttribute('aria-expanded', 'false');
+    document.body.style.overflow = '';
+  }
+
+  trigger.addEventListener('click', () => (menu.classList.contains('open') ? close() : open()));
+  backdrop.addEventListener('click', close);
+  closeBtn?.addEventListener('click', close);
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && menu.classList.contains('open')) close();
+  });
+  // Resizing past the breakpoint while open (rotating a tablet, or
+  // widening a desktop browser window) - the panel/backdrop are already
+  // hard-hidden above 860px via CSS regardless, but without this the body
+  // scroll lock and the trigger's own "open" state would stick around with
+  // no visible panel left to close them.
+  window.matchMedia('(min-width: 861px)').addEventListener('change', (e) => {
+    if (e.matches && menu.classList.contains('open')) close();
+  });
+}

package/src/scripts/search.ts

@@ -0,0 +1,155 @@
+// SearchModal.astro's own trigger button (rendered inside TopBar.astro) +
+// overlay/modal. Owns opening/closing the modal, the ⌘K/Ctrl K shortcut,
+// lazy-loading Pagefind on first open, and rendering results.
+export function initSearch(root: ParentNode) {
+  const trigger = root.querySelector<HTMLButtonElement>('[data-search-trigger]');
+  const overlay = root.querySelector<HTMLElement>('#wd-search-overlay');
+  const input = root.querySelector<HTMLInputElement>('#wd-search-input');
+  const resultsEl = root.querySelector<HTMLElement>('#wd-search-results');
+  if (!trigger || !overlay || !input || !resultsEl || trigger.dataset.wdInit) return;
+  trigger.dataset.wdInit = 'true';
+
+  // Most keyboards outside macOS/iOS don't have a command key - "Ctrl K"
+  // reads more naturally there than the ⌘ glyph.
+  const kbd = trigger.querySelector('.wd-search-kbd');
+  if (kbd && !/Mac|iPhone|iPad/.test(navigator.userAgent)) {
+    kbd.textContent = 'Ctrl K';
+  }
+
+  // Loaded lazily on first open rather than on every page load - most
+  // visits never open search, and the module + its wasm binary are pure
+  // overhead until someone actually wants to search. Pagefind only writes
+  // this file as a postbuild step, after Astro's own build (and therefore
+  // Vite's bundling) has already finished - see run-pagefind.js - so it
+  // never exists at `writedocs dev` time, and doesn't exist yet even
+  // during a production build's own Vite transform pass.
+  //
+  // `/* @vite-ignore */` alone doesn't stop Vite from trying to resolve it
+  // anyway: that comment only suppresses static analysis for a
+  // *non-literal* dynamic import specifier - a literal string like
+  // '/pagefind/pagefind.js' still gets resolved at transform time
+  // regardless of the comment, which crashes `writedocs dev` outright once
+  // this file exists in the template. Routing the literal through a
+  // variable first makes the specifier opaque to static analysis,
+  // deferring resolution to the browser at runtime - where the .catch()
+  // below handles "not built yet" gracefully instead.
+  let pagefind: any = null;
+  let loadPromise: Promise<any> | null = null;
+  function ensurePagefind() {
+    if (!loadPromise) {
+      const pagefindUrl = '/pagefind/pagefind.js';
+      loadPromise = import(/* @vite-ignore */ pagefindUrl)
+        .then((mod: any) => {
+          pagefind = mod;
+          return mod.init();
+        })
+        .then(() => pagefind)
+        .catch(() => {
+          resultsEl.innerHTML =
+            '<div class="wd-search-empty">Search isn\'t available in this preview - run a full build to index it.</div>';
+          return null;
+        });
+    }
+    return loadPromise;
+  }
+
+  let currentResults: HTMLElement[] = [];
+  let activeIndex = -1;
+
+  function setActive(index: number) {
+    currentResults.forEach((el) => el.classList.remove('wd-search-result-active'));
+    activeIndex = index >= 0 && index < currentResults.length ? index : -1;
+    if (activeIndex >= 0) {
+      currentResults[activeIndex].classList.add('wd-search-result-active');
+      currentResults[activeIndex].scrollIntoView({ block: 'nearest' });
+    }
+  }
+
+  async function runSearch(term: string) {
+    if (!term.trim()) {
+      resultsEl.innerHTML = '<div class="wd-search-hint">Start typing to search...</div>';
+      currentResults = [];
+      activeIndex = -1;
+      return;
+    }
+    const pf = await ensurePagefind();
+    if (!pf) return;
+    // debouncedSearch resolves to null when a newer keystroke has already
+    // superseded this call - pagefind's own debounce, on top of (not
+    // instead of) the plain `input` listener below, so a fast typist never
+    // races two searches rendering out of order.
+    const search = await pf.debouncedSearch(term, {}, 150);
+    if (search === null) return;
+    if (search.results.length === 0) {
+      resultsEl.innerHTML = '<div class="wd-search-empty">No results.</div>';
+      currentResults = [];
+      activeIndex = -1;
+      return;
+    }
+    const entries = await Promise.all(search.results.slice(0, 12).map((r: any) => r.data()));
+    resultsEl.innerHTML = '';
+    for (const data of entries) {
+      const a = document.createElement('a');
+      a.className = 'wd-search-result';
+      a.href = data.url;
+      const title = document.createElement('div');
+      title.className = 'wd-search-result-title';
+      title.textContent = data.meta?.title ?? data.url;
+      const excerpt = document.createElement('div');
+      excerpt.className = 'wd-search-result-excerpt';
+      // innerHTML (not textContent) is deliberate: pagefind returns this
+      // pre-sanitized with <mark> wrapping the matched terms, which is the
+      // whole point - a plain-text excerpt couldn't highlight anything.
+      excerpt.innerHTML = data.excerpt;
+      a.append(title, excerpt);
+      resultsEl.appendChild(a);
+    }
+    currentResults = Array.from(resultsEl.querySelectorAll('.wd-search-result'));
+    setActive(0);
+  }
+
+  function open() {
+    overlay.hidden = false;
+    document.body.style.overflow = 'hidden';
+    input.value = '';
+    resultsEl.innerHTML = '<div class="wd-search-hint">Start typing to search...</div>';
+    currentResults = [];
+    activeIndex = -1;
+    ensurePagefind();
+    input.focus();
+  }
+
+  function close() {
+    overlay.hidden = true;
+    document.body.style.overflow = '';
+    trigger.focus();
+  }
+
+  trigger.addEventListener('click', open);
+  overlay.addEventListener('click', (e) => {
+    if (e.target === overlay) close();
+  });
+  input.addEventListener('input', () => runSearch(input.value));
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setActive(activeIndex + 1);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setActive(activeIndex - 1);
+    } else if (e.key === 'Enter' && activeIndex >= 0) {
+      currentResults[activeIndex]?.click();
+    } else if (e.key === 'Escape') {
+      close();
+    }
+  });
+  document.addEventListener('keydown', (e) => {
+    if ((e.key === 'k' || e.key === 'K') && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      if (overlay.hidden) open();
+      else close();
+    } else if (e.key === 'Escape' && !overlay.hidden) {
+      close();
+    }
+  });
+}