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

package/src/toc-placement.ts

@@ -0,0 +1,71 @@
+/**
+ * Decide which TOC container(s) and right-rail region `DocsLayout` renders,
+ * given the `toc` placement mode and per-page facts. Factored out of
+ * `DocsLayout.astro` so the branching logic is unit-testable (the .astro
+ * file just consumes the result) — same pattern as `nav-filter.ts` etc.
+ *
+ * See plans/ask-branch1-placement-toc.md.
+ */
+
+export type TocMode = "top" | "popover" | "rail" | "off";
+
+export interface TocPlacement {
+  /** Classic right-hand TOC sidebar (the pre-`toc`-option layout). */
+  railToc: boolean;
+  /** Expandable "On this page" disclosure at the top of the article. */
+  topToc: boolean;
+  /** "On this page" dropdown in the header. */
+  popoverToc: boolean;
+  /**
+   * The right-rail plugin region (host for the `right-rail` named slot, e.g.
+   * an Ask AI panel). Present whenever the rail isn't the classic TOC's, and
+   * deliberately NOT gated on headings — so a plugin can dock on heading-less
+   * pages. Never shown on wide/API pages (no rail there).
+   */
+  regionRail: boolean;
+}
+
+/**
+ * Whether a page has enough displayable headings to warrant a TOC. The TOC
+ * (`DocsToc`) only lists depth `minDepth`–`maxDepth` (2–3 by default), so the
+ * page H1 never counts; and a TOC of a single entry isn't useful, so require
+ * `min` (2) by default. Pages like a landing/welcome page — H1 + prose, no
+ * sub-sections — therefore get no "On this page".
+ */
+export function hasDisplayableToc(
+  headings: { depth: number }[],
+  opts: { minDepth?: number; maxDepth?: number; min?: number } = {},
+): boolean {
+  const { minDepth = 2, maxDepth = 3, min = 2 } = opts;
+  let count = 0;
+  for (const h of headings) {
+    if (h.depth >= minDepth && h.depth <= maxDepth) count++;
+    if (count >= min) return true;
+  }
+  return false;
+}
+
+export interface TocPlacementInput {
+  /** Page has at least one heading to list. */
+  hasHeadings: boolean;
+  /** Wide/API layout — composes its own columns, so no right rail. */
+  wideLayout: boolean;
+}
+
+/**
+ * Resolve the placement flags. A TOC container only renders when there are
+ * headings to show; the region rail is independent of headings. `rail` and
+ * the region rail are mutually exclusive (they compete for the same column),
+ * and both are suppressed on wide pages.
+ */
+export function resolveTocPlacement(
+  toc: TocMode,
+  { hasHeadings, wideLayout }: TocPlacementInput,
+): TocPlacement {
+  return {
+    railToc: toc === "rail" && hasHeadings && !wideLayout,
+    topToc: toc === "top" && hasHeadings,
+    popoverToc: toc === "popover" && hasHeadings,
+    regionRail: toc !== "rail" && !wideLayout,
+  };
+}

package/src/version-redirect.ts

@@ -35,6 +35,20 @@ export interface AxisRedirectConfig {
   defaultLocale?: string;
   /** Full set of declared locale ids. Empty/undefined → axis inactive. */
   knownLocales?: string[];
+  /**
+   * First-segment names that aren't locale/version-axis-prefixable
+   * — e.g. taxonomy index paths like `tags`, `by-type`, `by-status`.
+   * Taxonomy routes emit a single global namespace shared across
+   * all locales / versions (one `/tags/` for the whole site, not
+   * one per locale), so the axis-redirect helper must skip them.
+   * Without this skip, chip hrefs to `/<basePath>/tags/...` would
+   * 302 to `/<basePath>/<defaultLocale>/tags/...` which 404s.
+   *
+   * Each entry is the first URL segment after basePath
+   * (no leading slash). Sourced from declared
+   * `taxonomies.<name>.indexPath` in `dogsbay.config.yml`.
+   */
+  globalPrefixes?: string[];
 }
 
 /**
@@ -88,6 +102,15 @@ export function shouldRedirectToDefaultVersion(
   // Skip Astro / Pagefind asset paths.
   if (segments[0].startsWith("_") || segments[0] === "pagefind") return null;
 
+  // Skip global-namespace prefixes (taxonomy index paths and similar
+  // routes that don't live under per-locale / per-version trees).
+  // Without this, chip hrefs to `/docs/tags/concept/rag/` get
+  // redirected to `/docs/<defaultLocale>/tags/concept/rag/` which
+  // 404s — the taxonomy routes are emitted once at the unprefixed
+  // path. See plans/beta-launch-followups.md.
+  const globalPrefixes = config.globalPrefixes ?? [];
+  if (globalPrefixes.includes(segments[0])) return null;
+
   // Greedy axis detection — locale outermost, version next.
   const knownLocales = new Set(config.knownLocales ?? []);
   const knownVersions = new Set(config.knownVersions ?? []);