@dogsbay/docs-layout 0.2.0-beta.10 → 0.2.0-beta.101

package/src/docs-nav-client.ts

@@ -0,0 +1,419 @@
+/**
+ * Client-side sidebar nav hydration.
+ *
+ * Fetches `/_dogsbay/nav.json` once per session, renders the tree DOM
+ * to mirror `@dogsbay/ui/sidebar/SidebarNavTree.astro`'s structure,
+ * and re-highlights the current page on each Astro view-transition
+ * page-load.
+ *
+ * Design constraints:
+ *   - DOM output matches SidebarNavTree exactly (same tags, classes,
+ *     data-attributes) so Tailwind's compiled CSS styles us correctly
+ *     and any sidebar-system selectors (e.g. `data-sidebar="nav-tree"`
+ *     hooks) keep working.
+ *   - Filter by `version` / `locale` matches `nav-filter.ts`'s SSR
+ *     filter so a multi-axis site renders the same nav as `ssr-full`
+ *     mode (without the multiplicative HTML cost).
+ *   - One fetch per session. The `nav.json` URL is served with
+ *     `Cache-Control: immutable` by Astro's static build (it lives
+ *     under `public/_dogsbay/`), so the browser cache holds it across
+ *     navigations.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+import { filterNavByAxis } from "./nav-filter.js";
+
+interface NavMark {
+  kind: "added" | "changed" | "removed" | "moved";
+  label?: string;
+  subtree?: boolean;
+}
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+  mark?: NavMark;
+}
+
+/**
+ * A state marker beside a nav label (release comparisons mark changed /
+ * new / removed pages; the same slot serves "new since your last
+ * visit", deprecation flags, version badges).
+ *
+ * Accessibility contract — mirrors SidebarNavMark.astro, which renders
+ * the server-side tree:
+ *  - **Never colour alone** (WCAG 1.4.1): a distinct GLYPH carries the
+ *    meaning, so it survives greyscale and colour-blindness; colour only
+ *    reinforces.
+ *  - **Survives forced-colors** (High Contrast strips backgrounds): the
+ *    glyph is real text, so it always renders.
+ *  - **Announced**: a visually-hidden word rides along, so the row reads
+ *    "MySQL, changed". It is a sibling span, NOT an aria-label on the
+ *    link — an aria-label would REPLACE the page name in the
+ *    accessibility tree, losing the label it exists to announce.
+ */
+const MARK_GLYPH: Record<NavMark["kind"], string> = {
+  added: "+",
+  changed: "•",
+  removed: "−",
+  moved: "→",
+};
+
+function buildMark(mark: NavMark): HTMLElement {
+  const text = mark.label ?? (mark.subtree ? `contains ${mark.kind}` : mark.kind);
+  const wrap = document.createElement("span");
+  wrap.className = "db-nav-mark";
+  wrap.dataset.navMark = mark.kind;
+  if (mark.subtree) wrap.dataset.navMarkSubtree = "";
+  wrap.title = text;
+
+  const glyph = document.createElement("span");
+  glyph.setAttribute("aria-hidden", "true");
+  glyph.textContent = MARK_GLYPH[mark.kind];
+  wrap.appendChild(glyph);
+
+  const sr = document.createElement("span");
+  sr.className = "sr-only";
+  sr.textContent = text;
+  wrap.appendChild(sr);
+
+  return wrap;
+}
+
+/**
+ * Module-level cache so multiple page loads in the same SPA session
+ * share the same fetched nav data. Cleared by re-loads (full page
+ * navigations) but Astro's view transitions re-execute the script
+ * module without reloading the page — so on view-transition the
+ * cached promise is reused and no extra fetch fires.
+ */
+let navPromise: Promise<NavItem[]> | null = null;
+
+function fetchNav(url: string): Promise<NavItem[]> {
+  if (!navPromise) {
+    navPromise = fetch(url, { credentials: "same-origin" }).then((r) => {
+      if (!r.ok) throw new Error(`nav.json fetch failed: ${r.status}`);
+      return r.json() as Promise<NavItem[]>;
+    });
+  }
+  return navPromise;
+}
+
+function normalize(path: string): string {
+  return path.replace(/\/$/, "") || "/";
+}
+
+function hasActiveDescendant(item: NavItem, current: string): boolean {
+  if (item.href && normalize(item.href) === current) return true;
+  return item.children?.some((c) => hasActiveDescendant(c, current)) ?? false;
+}
+
+/**
+ * Render a single nav item into a `<li>` DOM node. Matches
+ * SidebarNavTree's per-level class set exactly so styling stays in
+ * sync. Padding is computed from `level` the same way (`8 + level*12`
+ * pixels) so indentation lines up across the same render.
+ */
+export function renderItem(item: NavItem, current: string, level: number): HTMLLIElement {
+  const li = document.createElement("li");
+  li.dataset.sidebar = "nav-tree-item";
+
+  const active = item.href ? normalize(item.href) === current : false;
+  const hasChildren = !!item.children && item.children.length > 0;
+  const padLeft = `${8 + level * 12}px`;
+  const heightClass = level === 0 ? "h-8" : "h-7";
+
+  if (hasChildren && item.href) {
+    // A branch that is ALSO a page (section landing page) uses the APG
+    // "disclosure navigation" pattern: a real link (navigates) and a
+    // SEPARATE toggle <button> (expands/collapses), as siblings. Nesting
+    // a focusable <a> inside the interactive <summary> — as this did
+    // before — is an axe `nested-interactive` violation ("interactive
+    // controls must not be nested"). Native <details> can't hold a
+    // visible-when-collapsed header link without that nesting, so a
+    // page-branch drops <details> for link + button + sibling submenu.
+    const open = active || hasActiveDescendant(item, current);
+    const submenuId = `nav-sub-${item.href.replace(/[^a-z0-9]+/gi, "-")}-${level}`;
+
+    const row = document.createElement("div");
+    row.className = [
+      "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    row.style.paddingLeft = padLeft;
+
+    const toggle = document.createElement("button");
+    toggle.type = "button";
+    toggle.dataset.navToggle = "";
+    toggle.setAttribute("aria-controls", submenuId);
+    toggle.setAttribute("aria-expanded", String(open));
+    toggle.setAttribute("aria-label", `Toggle ${item.label} section`);
+    toggle.className =
+      "shrink-0 rounded outline-none ring-sidebar-ring focus-visible:ring-2";
+    toggle.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>';
+    row.appendChild(toggle);
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      row.appendChild(iconSpan);
+    }
+
+    const link = document.createElement("a");
+    link.className =
+      "min-w-0 flex-1 truncate text-inherit no-underline outline-none ring-sidebar-ring focus-visible:ring-2";
+    link.href = item.href;
+    link.textContent = item.label;
+    link.dataset.navHref = item.href; // rehighlight keys off this
+    if (active) link.dataset.active = "true";
+    row.appendChild(link);
+
+    if (item.mark) {
+      // A SUBTREE mark describes DESCENDANTS — never strike through this
+      // row for it (a surviving group whose child was deleted would read
+      // as a deleted section).
+      if (!item.mark.subtree) link.dataset.navMarkRow = item.mark.kind;
+      row.appendChild(buildMark(item.mark));
+    }
+
+    const submenu = document.createElement("ul");
+    submenu.id = submenuId;
+    submenu.dataset.navSubmenu = "";
+    submenu.className = "flex min-w-0 flex-col";
+    submenu.dataset.sidebar = "nav-tree";
+    submenu.dataset.level = String(level + 1);
+    for (const child of item.children!) {
+      submenu.appendChild(renderItem(child, current, level + 1));
+    }
+    if (!open) submenu.hidden = true;
+
+    toggle.addEventListener("click", () => {
+      const isOpen = toggle.getAttribute("aria-expanded") === "true";
+      toggle.setAttribute("aria-expanded", String(!isOpen));
+      submenu.hidden = isOpen;
+    });
+
+    li.appendChild(row);
+    li.appendChild(submenu);
+  } else if (hasChildren) {
+    // Pure grouping label (no href): native <details>/<summary> is fully
+    // accessible here — the summary is the only interactive control, and
+    // its label is a plain <span>. Zero-JS expand/collapse.
+    const details = document.createElement("details");
+    if (active || hasActiveDescendant(item, current)) details.open = true;
+
+    const summary = document.createElement("summary");
+    summary.className = [
+      "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
+      heightClass,
+    ]
+      .filter(Boolean)
+      .join(" ");
+    summary.style.paddingLeft = padLeft;
+
+    summary.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>';
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      summary.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "min-w-0 flex-1 truncate";
+    label.textContent = item.label;
+    summary.appendChild(label);
+
+    // A collapsed group HIDES its children, so a change inside must
+    // signal outward — the same visibility rule the diff renderer
+    // applies to tabs.
+    if (item.mark) summary.appendChild(buildMark(item.mark));
+
+    details.appendChild(summary);
+
+    const childUl = document.createElement("ul");
+    childUl.className = "flex min-w-0 flex-col";
+    childUl.dataset.sidebar = "nav-tree";
+    childUl.dataset.level = String(level + 1);
+    for (const child of item.children!) {
+      childUl.appendChild(renderItem(child, current, level + 1));
+    }
+    details.appendChild(childUl);
+
+    li.appendChild(details);
+  } else {
+    const a = document.createElement("a");
+    a.href = item.href || "#";
+    a.className = [
+      "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    a.style.paddingLeft = padLeft;
+    if (active) a.dataset.active = "true";
+    if (item.href) a.dataset.navHref = item.href;
+
+    // Spacer to align leaf text with branch text (which has a chevron).
+    const spacer = document.createElement("span");
+    spacer.className = "size-4 shrink-0";
+    a.appendChild(spacer);
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      a.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "min-w-0 flex-1 truncate";
+    label.textContent = item.label;
+    a.appendChild(label);
+
+    if (item.mark) {
+      // strikethrough only for a page that IS removed, never for an
+      // aggregate about its children
+      if (!item.mark.subtree) a.dataset.navMarkRow = item.mark.kind;
+      a.appendChild(buildMark(item.mark));
+    }
+
+    li.appendChild(a);
+  }
+
+  return li;
+}
+
+export function renderTree(items: NavItem[], current: string, root: HTMLElement): void {
+  const ul = document.createElement("ul");
+  ul.className =
+    "flex min-w-0 flex-col w-full group-data-[collapsible=icon]:hidden";
+  ul.dataset.sidebar = "nav-tree";
+  ul.dataset.level = "0";
+  for (const item of items) {
+    ul.appendChild(renderItem(item, current, 0));
+  }
+  // Replace skeleton in one DOM op so there's no flash of partial state.
+  root.replaceChildren(ul);
+  root.removeAttribute("aria-busy");
+}
+
+/**
+ * Re-highlight the active item without rebuilding the whole tree.
+ * Used on `astro:page-load` when view transitions land on a new
+ * route — we re-toggle the `data-active` attribute and re-apply the
+ * active classes, then expand the new active branch's ancestors.
+ *
+ * Cheaper than a full re-render (no fetch, no DOM rebuild). For
+ * the wider hydration loop we still re-render when a brand-new nav
+ * structure is needed (e.g. switching versions), but path-only
+ * navigation just re-highlights.
+ */
+function rehighlight(root: HTMLElement, current: string): void {
+  const ACTIVE_CLASSES = [
+    "bg-sidebar-accent",
+    "font-medium",
+    "text-sidebar-accent-foreground",
+  ];
+  const items = root.querySelectorAll<HTMLElement>("[data-nav-href]");
+  for (const el of Array.from(items)) {
+    const href = el.dataset.navHref;
+    const active = !!href && normalize(href) === current;
+    if (active) {
+      el.dataset.active = "true";
+      el.classList.add(...ACTIVE_CLASSES);
+    } else {
+      delete el.dataset.active;
+      el.classList.remove(...ACTIVE_CLASSES);
+    }
+  }
+  // Expand ancestors of the new active item — both native <details>
+  // groups and the button-driven [data-nav-submenu] disclosures used by
+  // section-landing (href) branches.
+  const active = root.querySelector<HTMLElement>('[data-active="true"]');
+  if (active) {
+    let parent: HTMLElement | null = active.parentElement;
+    while (parent) {
+      if (parent.tagName === "DETAILS") {
+        (parent as HTMLDetailsElement).open = true;
+      }
+      if (parent.matches("[data-nav-submenu]")) {
+        parent.hidden = false;
+        const toggle = root.querySelector<HTMLElement>(
+          `[data-nav-toggle][aria-controls="${parent.id}"]`,
+        );
+        toggle?.setAttribute("aria-expanded", "true");
+      }
+      parent = parent.parentElement;
+    }
+  }
+}
+
+/**
+ * Public entry point. Called once from `<DocsNavClient />`'s inline
+ * script tag. Idempotent — subsequent calls (e.g. from view
+ * transitions) are no-ops once the tree has been rendered; they just
+ * re-highlight against the new pathname.
+ */
+export async function hydrateDocsNav(): Promise<void> {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+
+  const navUrl = root.dataset.navUrl;
+  if (!navUrl) {
+    console.warn("docs-nav: missing data-nav-url");
+    return;
+  }
+  const current = normalize(root.dataset.currentPath || location.pathname);
+  const basePath = root.dataset.basePath || "";
+  const namespace = root.dataset.namespace || undefined;
+  const version = root.dataset.version || undefined;
+  const locale = root.dataset.locale || undefined;
+
+  try {
+    const nav = await fetchNav(navUrl);
+    const filtered = filterNavByAxis(nav, {
+      // Pass basePath through as-is — an empty basePath (root-served
+      // site) must stay "", matching the SSR path's `?? "/docs"`
+      // (which keeps ""). Coercing "" → "/docs" makes the filter look
+      // for `/docs/…` bucket hrefs that don't exist and blanks the
+      // whole sidebar on a root-served multi-source site.
+      basePath,
+      namespace: namespace || undefined,
+      version: version || undefined,
+      locale: locale || undefined,
+    });
+    renderTree(filtered, current, root);
+  } catch (err) {
+    console.error("docs-nav: hydration failed", err);
+    root.setAttribute("aria-busy", "false");
+    // Keep skeleton so layout doesn't collapse on failure; a real
+    // user will reload or follow the noscript link.
+  }
+}
+
+// Re-run on view transitions. astro:page-load fires both on initial
+// load and after each ClientRouter transition; the module-level
+// `navPromise` cache makes the post-transition path a fast
+// highlight-only pass without re-fetching.
+document.addEventListener("astro:page-load", () => {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+  // If tree is already rendered (no aria-busy), just re-highlight.
+  if (root.getAttribute("aria-busy") === null) {
+    const current = normalize(root.dataset.currentPath || location.pathname);
+    rehighlight(root, current);
+  } else {
+    void hydrateDocsNav();
+  }
+});

package/src/json-ld.ts

@@ -53,3 +53,115 @@ export function normalizeCustomJsonLd(
   if (Array.isArray(raw)) return raw;
   return [raw];
 }
+
+export interface BuildArticleJsonLdOptions {
+  /** Already-resolved Schema.org `@type` (output of jsonLdTypeFor). */
+  type: string;
+  title: string;
+  /** Site name — used as the `provider` Organization for Course. */
+  siteName: string;
+  keywords: string[];
+  description?: string;
+  image?: string;
+  url?: string;
+  /**
+   * Page headings — used to synthesize `step[]` for HowTo. Each
+   * H2 (or H3 if no H2s exist) becomes a HowToStep with a deep
+   * link to the heading id.
+   */
+  headings?: ReadonlyArray<{ depth: number; slug: string; text: string }>;
+}
+
+/**
+ * Build the JSON-LD payload for the page's primary structured-data
+ * block, shaped per `@type`. The earlier implementation emitted
+ * Article-shaped fields (`headline`) regardless of @type, which
+ * meant HowTo / Course pages failed Google's Rich Results
+ * requirements (HowTo needs `name` + `step`, Course needs `name` +
+ * `description` + `provider`). See
+ * `packages/cli/src/audit/rules/seo/json-ld-required-fields.ts`
+ * for the validator that catches this.
+ *
+ * Schema.org's `name` is a Thing-level field accepted by every
+ * @type, so we always emit it. `headline` is added on top for
+ * Article-family types (Article, TechArticle) because Google's
+ * Rich Results validator specifically requires it there. HowTo
+ * gets a synthesized `step[]` from the page's H2 headings (each
+ * H2 = one procedure step); Course gets a `provider` Organization
+ * built from `siteName`.
+ */
+export function buildArticleJsonLd(
+  opts: BuildArticleJsonLdOptions,
+): Record<string, unknown> {
+  const { type, title, siteName, keywords, description, image, url, headings } =
+    opts;
+
+  const block: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": type,
+    name: title,
+  };
+  // Only when there are any. An empty `keywords: ""` asserts the page
+  // has no topics, which is a different claim from staying silent.
+  if (keywords.length > 0) block.keywords = keywords.join(", ");
+
+  if (type === "Article" || type === "TechArticle") {
+    block.headline = title;
+  }
+
+  if (description) block.description = description;
+  if (image) block.image = image;
+  if (url) block.url = url;
+
+  if (type === "HowTo") {
+    let stepHeadings = (headings ?? []).filter((h) => h.depth === 2);
+    if (stepHeadings.length === 0) {
+      stepHeadings = (headings ?? []).filter((h) => h.depth === 3);
+    }
+    block.step = stepHeadings.map((h) => ({
+      "@type": "HowToStep",
+      name: h.text,
+      url: url ? `${url}#${h.slug}` : `#${h.slug}`,
+    }));
+  }
+
+  if (type === "Course") {
+    block.provider = { "@type": "Organization", name: siteName };
+    if (!block.description) block.description = title;
+  }
+
+  return block;
+}
+
+/**
+ * Identity structured data for a page that is not an article — a
+ * homepage, a landing page, a section index.
+ *
+ * Exists because the article block is gated on `ogType === "article"`,
+ * so those pages emitted NO structured data at all. An external agent
+ * audit reported "No JSON-LD structured data found on homepage", which
+ * was accurate: the one page most likely to be an agent's entry point
+ * was the one describing itself the least.
+ *
+ * `WebSite` rather than `Organization` or `SoftwareApplication` on
+ * purpose. Those are claims about what the site's OWNER is, and
+ * guessing wrong is worse than saying less — a docs site for a product
+ * is not itself the product. Owners wanting a stronger identity type
+ * add it through `customJsonLd`, which layers on top of this.
+ */
+export function buildWebSiteJsonLd(opts: {
+  siteName: string;
+  title: string;
+  description?: string;
+  url?: string;
+}): Record<string, unknown> {
+  const block: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: opts.siteName,
+  };
+  if (opts.title && opts.title !== opts.siteName) block.headline = opts.title;
+  if (opts.description) block.description = opts.description;
+  if (opts.url) block.url = opts.url;
+  return block;
+}

package/src/link-icons.ts

@@ -0,0 +1,54 @@
+/**
+ * Internal/external link-icon affordance — the tiny bit of logic behind
+ * the `data-link-icons` + `--db-link-icon-*` attributes DocsLayout stamps
+ * on `<body>`. Classification itself is pure CSS (by href shape); this
+ * only turns the configured glyphs into the attribute + custom-property
+ * values. See plans/link-resolution-and-icons.md.
+ */
+
+export interface LinkIcons {
+  /** Glyph after external links (absolute / protocol-relative href). */
+  external?: string;
+  /** Glyph after internal links (root / relative href). */
+  internal?: string;
+}
+
+export interface LinkIconAttrs {
+  /**
+   * Space-separated active kinds for `data-link-icons` (`"external"`,
+   * `"internal"`, or both) — undefined when the feature is off, so the
+   * attribute is omitted entirely.
+   */
+  tokens?: string;
+  /**
+   * Inline `style` value setting the `--db-link-icon-*` custom
+   * properties to the (single-quoted, CSS-string-safe) glyphs —
+   * undefined when nothing is active.
+   */
+  style?: string;
+}
+
+/** CSS-string-escape a glyph so it's a valid single-quoted `content:` value. */
+function cssString(glyph: string): string {
+  return glyph.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
+/**
+ * Build the `<body>` attributes for the link-icon feature. A side is
+ * active only when its glyph is a non-empty string; an absent config (or
+ * all-empty) yields `{}` so DocsLayout emits no attributes.
+ */
+export function linkIconAttrs(icons: LinkIcons | undefined): LinkIconAttrs {
+  const external = icons?.external?.trim() ? icons.external : "";
+  const internal = icons?.internal?.trim() ? icons.internal : "";
+  const tokens = [external ? "external" : "", internal ? "internal" : ""]
+    .filter(Boolean)
+    .join(" ");
+  const style = [
+    external ? `--db-link-icon-external: '${cssString(external)}'` : "",
+    internal ? `--db-link-icon-internal: '${cssString(internal)}'` : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+  return { tokens: tokens || undefined, style: style || undefined };
+}

package/src/markdown-negotiation.ts

@@ -7,6 +7,11 @@
  * Returns the path to rewrite to (the `.md` mirror endpoint) when the
  * request should be served as markdown; returns `null` when the normal
  * HTML response should pass through.
+ *
+ * `basePath` is the prefix the site is SERVED at (Dogsbay's combined
+ * urlBase + basePath). It is needed only to recognise the site index,
+ * whose mirror is `<base>/index.md` rather than `<base>.md` — see
+ * `shouldRewriteToMarkdown`.
  */
 
 const Q_PARAM_RE = /^\s*q\s*=\s*([0-9.]+)\s*$/i;
@@ -28,6 +33,7 @@ const Q_PARAM_RE = /^\s*q\s*=\s*([0-9.]+)\s*$/i;
 export function shouldRewriteToMarkdown(
   accept: string | null | undefined,
   pathname: string,
+  basePath = "",
 ): string | null {
   if (!accept) return null;
   if (!acceptsMarkdown(accept)) return null;
@@ -35,8 +41,38 @@ export function shouldRewriteToMarkdown(
   if (hasNonHtmlExtension(pathname)) return null;
 
   const trimmed = pathname.replace(/\/$/, "");
-  const target = trimmed === "" ? "/.md" : `${trimmed}.md`;
-  return target;
+  const base = basePath.replace(/\/+$/, "");
+
+  // A request outside the served prefix is not ours to rewrite. Without
+  // this guard, `("/", "/docs")` fell through to `"" + ".md"` — a
+  // RELATIVE target, resolved against whatever the request path was.
+  if (base && trimmed !== base && !trimmed.startsWith(`${base}/`)) return null;
+
+  // The site index is emitted as `index.md.ts`, so its mirror is
+  // `<base>/index.md`. Every other page emitted by the shipped importers
+  // has its mirror at `<path>.md`: Dogsbay builds in Astro's directory
+  // format, so a leaf at `/getting-started/` maps to
+  // `/getting-started.md`, and a directory index like `guides/index.md`
+  // is NORMALIZED to slug `guides` (see import-mkdocs.ts's
+  // `.replace(/\/index$/, "")`), emitting `guides.astro` + `guides.md.ts`
+  // — so `/guides.md` exists too.
+  //
+  // Appending `.md` to the site index produced `/.md` (root-served) or
+  // `/blog.md` (mounted); neither exists, and `/blog.md` additionally
+  // falls OUTSIDE the `/blog/*` Workers route. Leaf and index URLs both
+  // carry a trailing slash, so only the base comparison distinguishes
+  // them.
+  //
+  // CAVEAT: a caller driving `exportAstroProject` directly with an
+  // unnormalized `<dir>/index` slug gets `src/pages/<dir>/index.astro`
+  // (served `/<dir>/`) whose only mirror is `/<dir>/index.md`, and this
+  // returns `/<dir>.md` — a 404. No shipped importer does that. If one
+  // ever should, generalize the sibling `.md.ts` emitter in
+  // `format-astro/src/project.ts` rather than guessing here from a URL
+  // that cannot distinguish the two shapes.
+  if (trimmed === base) return `${base}/index.md`;
+
+  return `${trimmed}.md`;
 }
 
 function acceptsMarkdown(accept: string): boolean {