@dogsbay/docs-layout 0.2.0-beta.87 → 0.2.0-beta.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.87",
+  "version": "0.2.0-beta.89",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.87",
-    "@dogsbay/primitives": "0.2.0-beta.87"
+    "@dogsbay/ui": "0.2.0-beta.89",
+    "@dogsbay/primitives": "0.2.0-beta.89"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/DocsLayout.astro

@@ -35,7 +35,7 @@ import DocsNavClient from "./DocsNavClient.astro";
 import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
-import { resolveTocPlacement, type TocMode } from "./toc-placement.js";
+import { resolveTocPlacement, hasDisplayableToc, type TocMode } from "./toc-placement.js";
 import DocsFooter from "./DocsFooter.astro";
 import SearchDialog from "./SearchDialog.astro";
 import TagList from "./TagList.astro";
@@ -528,7 +528,10 @@ const hasMetaStrip = (
 // TOC placement: which container(s) + the right-rail plugin region render.
 // Logic lives in toc-placement.ts so it's unit-tested; this file just consumes.
 const tocPlacement = resolveTocPlacement(toc, {
-  hasHeadings: headings.length > 0,
+  // Only show a TOC when the page has 2+ displayable headings (depth 2–3);
+  // the H1 doesn't count and a one-item TOC is noise. Keeps "On this page"
+  // off landing/welcome pages that are just an H1 + prose.
+  hasHeadings: hasDisplayableToc(headings),
   wideLayout: !!wideLayout,
 });
 

package/src/toc-placement.ts

@@ -25,6 +25,26 @@ export interface TocPlacement {
   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;