@writedocs/generator 0.8.0 → 0.9.0

package/src/layout/components/TopBar.astro

@@ -39,7 +39,7 @@ const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark,
 // products, or a dropdown used as a nested path segment) on the right,
 // and a second row underneath for tabs plus the always-visible global
 // dropdowns - both of which behave like a row of labeled links rather
-// than a single current-value switcher.
+// than a single current-value switcher. Tabs inside a tab get a third row.
 //
 // A dropdown container nested directly inside a tab (writedocs.json's "API
 // Reference" tab having a `dropdowns` array instead of `pages`) reads as
@@ -56,7 +56,10 @@ const switcherSelectors = selectors.filter(
   (sel, i) => sel.kind !== 'tab' && !(sel.kind === 'dropdown' && selectors[i - 1]?.kind === 'tab')
 );
 const tabSelectors = selectors.filter((sel) => sel.kind === 'tab');
-const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
+// One row per level of tabs: a tab holding its own tabs gets a second row
+// underneath, with that tab's tabs. The global dropdowns stay in the first
+// row, which renders on its own when there are only those.
+const tabRows = tabSelectors.length > 0 ? tabSelectors : globalDropdowns.length > 0 ? [null] : [];
 ---
 <header class="wd-topbar">
   <div class="wd-topbar-row wd-topbar-row-brand">
@@ -86,7 +89,7 @@ const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
       <a class="wd-topbar-brand" href="/">
         {logoLight && <img src={logoLight} alt={config.name} height="24" class="wd-logo-light" />}
         {logoDark && <img src={logoDark} alt={config.name} height="24" class="wd-logo-dark" />}
-        {brandLabel && <span>{brandLabel}</span>}
+        {brandLabel && <span title={brandLabel}>{brandLabel}</span>}
       </a>
 
       {switcherSelectors.length > 0 && (
@@ -100,7 +103,7 @@ const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
             const current = sel.options.find((o) => o.active) ?? sel.options[0];
             return (
               <div class="wd-dropdown" data-selector-kind={sel.kind}>
-                <button type="button" class="wd-dropdown-trigger wd-switcher-trigger" aria-haspopup="true" aria-expanded="false">
+                <button type="button" class="wd-dropdown-trigger wd-switcher-trigger" aria-expanded="false">
                   <AppIcon icon={current.icon} class="wd-tab-icon" />
                   {current.label}
                   {current.tag && <span class="wd-selector-tag">{current.tag}</span>}
@@ -108,13 +111,12 @@ const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
                     <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
                   </svg>
                 </button>
-                <div class="wd-dropdown-menu" role="menu">
+                <div class="wd-dropdown-menu">
                   <div class="wd-dropdown-menu-panel">
                     {sel.options.map((opt) => (
                       <a
                         href={opt.href}
-                        role="menuitem"
-                        class={opt.active ? 'active' : ''}
+                        class={opt.active ? 'active' : ''} aria-current={opt.active ? 'true' : undefined}
                         target={isExternalHref(opt.href) ? '_blank' : undefined}
                         rel={isExternalHref(opt.href) ? 'noopener noreferrer' : undefined}
                       >
@@ -161,7 +163,6 @@ const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
           <button
             type="button"
             class="wd-dropdown-trigger wd-topbar-links-toggle"
-            aria-haspopup="true"
             aria-expanded="false"
             aria-label="More links"
           >
@@ -171,12 +172,11 @@ const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
               <circle cx="2" cy="14" r="1.7" fill="currentColor" />
             </svg>
           </button>
-          <div class="wd-dropdown-menu" role="menu">
+          <div class="wd-dropdown-menu">
             <div class="wd-dropdown-menu-panel">
               {config.topbar.links.map((link) => (
                 <a
                   href={link.href}
-                  role="menuitem"
                   target={isExternalHref(link.href) ? '_blank' : undefined}
                   rel={isExternalHref(link.href) ? 'noopener noreferrer' : undefined}
                   aria-label={!link.label ? link.icon : undefined}
@@ -206,106 +206,125 @@ const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
     </div>
   </div>
 
-  {showSecondRow && (
-    <div class="wd-topbar-row wd-topbar-row-tabs">
+  {tabRows.map((sel, row) => (
+    <div class={`wd-topbar-row wd-topbar-row-tabs${row > 0 ? ' wd-topbar-row-subtabs' : ''}`}>
       <div class="wd-topbar-inner">
-        <nav class="wd-topbar-tabs" aria-label="Sections">
-          {tabSelectors.map((sel) =>
-            sel.options.map((opt) =>
-              opt.dropdown ? (
-                // A tab whose own content is `dropdowns` (not `pages`)
-                // renders as a dropdown-trigger in place of the plain
-                // pill - the tab's own label/icon stay on the trigger
-                // (not "whichever dropdown is current", so it reads as
-                // "this tab, which happens to expand" rather than
-                // jumping around as you navigate its sub-pages), and its
-                // dropdowns become the menu.
-                <div class="wd-dropdown" data-selector-kind="tab">
-                  <button
-                    type="button"
-                    class={`wd-dropdown-trigger wd-tab-link ${opt.active ? 'active' : ''}`}
-                    aria-haspopup="true"
-                    aria-expanded="false"
+        {/* More tabs than fit: the row slides sideways instead of wrapping,
+            with an arrow on each side that has more (src/scripts/tabs-strip.ts).
+            The arrows are only for the mouse - keyboard focus slides a tab
+            into view by itself. */}
+        <div class="wd-tabs-strip" data-tabs-strip>
+          <button type="button" class="wd-tabs-arrow wd-tabs-arrow-prev" tabindex="-1" aria-hidden="true" data-tabs-prev>
+            <svg width="14" height="14" viewBox="0 0 14 14" aria-hidden="true">
+              <path d="M8.5 3L4.5 7L8.5 11" stroke="currentColor" stroke-width="1.6" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+            </svg>
+          </button>
+          <div class="wd-tabs-viewport">
+            <nav class="wd-topbar-tabs" aria-label={row === 0 ? 'Sections' : 'Subsections'}>
+              {(sel?.options ?? []).map((opt) =>
+                opt.dropdown ? (
+                  // A tab whose own content is `dropdowns` (not `pages`)
+                  // renders as a dropdown-trigger in place of the plain
+                  // pill - the tab's own label/icon stay on the trigger
+                  // (not "whichever dropdown is current", so it reads as
+                  // "this tab, which happens to expand" rather than
+                  // jumping around as you navigate its sub-pages), and its
+                  // dropdowns become the menu.
+                  <div class="wd-dropdown" data-selector-kind="tab">
+                    <button
+                      type="button"
+                      class={`wd-dropdown-trigger wd-tab-link ${opt.active ? 'active' : ''}`}
+                      aria-expanded="false"
+                    >
+                      <AppIcon icon={opt.icon} class="wd-tab-icon" />
+                      {opt.label}
+                      <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                        <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+                      </svg>
+                    </button>
+                    <div class="wd-dropdown-menu">
+                      <div class="wd-dropdown-menu-panel">
+                        {opt.dropdown.map((d) => (
+                          <a
+                            href={d.href}
+                            class={d.active ? 'active' : ''} aria-current={d.active ? 'true' : undefined}
+                            target={isExternalHref(d.href) ? '_blank' : undefined}
+                            rel={isExternalHref(d.href) ? 'noopener noreferrer' : undefined}
+                          >
+                            <AppIcon icon={d.icon} class="wd-tab-icon" />
+                            {d.label}
+                          </a>
+                        ))}
+                      </div>
+                    </div>
+                  </div>
+                ) : (
+                  <a
+                    href={opt.href}
+                    class={`wd-tab-link ${opt.active ? 'active' : ''}`}
+                    aria-current={opt.active ? 'true' : undefined}
+                    target={isExternalHref(opt.href) ? '_blank' : undefined}
+                    rel={isExternalHref(opt.href) ? 'noopener noreferrer' : undefined}
                   >
                     <AppIcon icon={opt.icon} class="wd-tab-icon" />
                     {opt.label}
-                    <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
-                      <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
-                    </svg>
-                  </button>
-                  <div class="wd-dropdown-menu" role="menu">
-                    <div class="wd-dropdown-menu-panel">
-                      {opt.dropdown.map((d) => (
-                        <a
-                          href={d.href}
-                          role="menuitem"
-                          class={d.active ? 'active' : ''}
-                          target={isExternalHref(d.href) ? '_blank' : undefined}
-                          rel={isExternalHref(d.href) ? 'noopener noreferrer' : undefined}
-                        >
-                          <AppIcon icon={d.icon} class="wd-tab-icon" />
-                          {d.label}
-                        </a>
-                      ))}
+                  </a>
+                )
+              )}
+              {row === 0 &&
+                globalDropdowns.map((d) =>
+                  d.href !== null ? (
+                    <a
+                      href={d.href}
+                      class="wd-tab-link"
+                      target={isExternalHref(d.href) ? '_blank' : undefined}
+                      rel={isExternalHref(d.href) ? 'noopener noreferrer' : undefined}
+                    >
+                      <AppIcon icon={d.icon} class="wd-tab-icon" />
+                      {d.label}
+                    </a>
+                  ) : (
+                    <div class="wd-dropdown">
+                      <button type="button" class="wd-dropdown-trigger" aria-expanded="false">
+                        <AppIcon icon={d.icon} class="wd-tab-icon" />
+                        {d.label}
+                        <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                          <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+                        </svg>
+                      </button>
+                      <div class="wd-dropdown-menu">
+                        <div class="wd-dropdown-menu-panel">
+                          {d.items.map((item) => (
+                            <a href={item.href} class={item.active ? 'active' : ''} aria-current={item.active ? 'true' : undefined}>{item.label}</a>
+                          ))}
+                        </div>
+                      </div>
                     </div>
-                  </div>
-                </div>
-              ) : (
-                <a
-                  href={opt.href}
-                  class={`wd-tab-link ${opt.active ? 'active' : ''}`}
-                  target={isExternalHref(opt.href) ? '_blank' : undefined}
-                  rel={isExternalHref(opt.href) ? 'noopener noreferrer' : undefined}
-                >
-                  <AppIcon icon={opt.icon} class="wd-tab-icon" />
-                  {opt.label}
-                </a>
-              )
-            )
-          )}
-          {globalDropdowns.map((d) =>
-            d.href !== null ? (
-              <a
-                href={d.href}
-                class="wd-tab-link"
-                target={isExternalHref(d.href) ? '_blank' : undefined}
-                rel={isExternalHref(d.href) ? 'noopener noreferrer' : undefined}
-              >
-                <AppIcon icon={d.icon} class="wd-tab-icon" />
-                {d.label}
-              </a>
-            ) : (
-              <div class="wd-dropdown">
-                <button type="button" class="wd-dropdown-trigger" aria-haspopup="true" aria-expanded="false">
-                  <AppIcon icon={d.icon} class="wd-tab-icon" />
-                  {d.label}
-                  <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
-                    <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
-                  </svg>
-                </button>
-                <div class="wd-dropdown-menu" role="menu">
-                  <div class="wd-dropdown-menu-panel">
-                    {d.items.map((item) => (
-                      <a href={item.href} role="menuitem" class={item.active ? 'active' : ''}>{item.label}</a>
-                    ))}
-                  </div>
-                </div>
-              </div>
-            )
-          )}
-        </nav>
+                  )
+                )}
+            </nav>
+          </div>
+          <button type="button" class="wd-tabs-arrow wd-tabs-arrow-next" tabindex="-1" aria-hidden="true" data-tabs-next>
+            <svg width="14" height="14" viewBox="0 0 14 14" aria-hidden="true">
+              <path d="M5.5 3L9.5 7L5.5 11" stroke="currentColor" stroke-width="1.6" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+            </svg>
+          </button>
+        </div>
       </div>
     </div>
-  )}
+  ))}
 </header>
 <script>
   import { initDropdowns } from '../../scripts/dropdowns';
   import { initThemeToggle } from '../../scripts/theme-toggle';
+  import { initTabsStrips } from '../../scripts/tabs-strip';
 
   initDropdowns(document);
   initThemeToggle(document);
+  initTabsStrips(document);
   document.addEventListener('astro:page-load', () => {
     initDropdowns(document);
     initThemeToggle(document);
+    initTabsStrips(document);
   });
 </script>

package/src/layout/styles/search-modal.css

@@ -95,6 +95,33 @@
    browser's default yellow highlight, to match the rest of the site's own
    "tint primary" pattern for active/matched state (sidebar links,
    selector options, ...). */
+/* Where the page sits ("API Reference › Webhooks"), between the title and
+   the excerpt. */
+.wd-search-result-section {
+  font-size: 0.75rem;
+  color: var(--wd-text-muted);
+  margin: -0.15rem 0 0.3rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+/* Under the results: which version/language/product they're from, and the
+   switch to search the whole site. */
+.wd-search-scope {
+  padding: 0.6rem 0.8rem 0.3rem;
+  font-size: 0.8rem;
+  color: var(--wd-text-muted);
+}
+.wd-search-scope-toggle {
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  color: var(--wd-primary);
+  cursor: pointer;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
 .wd-search-result-excerpt mark {
   background: none;
   color: var(--wd-primary);

package/src/layout/styles/topbar.css

@@ -41,6 +41,17 @@
      active tab. */
   padding-bottom: 0;
 }
+/* A tab holding its own tabs: those go in a row underneath. The first row
+   gets a divider for its active tab's underline to land on, and the second
+   row's tabs are a step lighter, so the two levels read as section and
+   subsection. */
+.wd-topbar-row-tabs:not(:last-child) {
+  border-bottom: 1px solid var(--wd-border);
+}
+.wd-topbar-row-subtabs .wd-tab-link {
+  font-size: 0.85rem;
+  font-weight: 500;
+}
 .wd-topbar-brand {
   display: flex;
   align-items: center;
@@ -56,14 +67,29 @@
      see this file's own top comment. */
   color: var(--wd-navbar-foreground);
   font-size: 1.05rem;
+  /* When the row runs short, a long site name gives way (ending in "..."),
+     not the switchers next to it - their labels would break onto two lines. */
+  flex-shrink: 1;
+  min-width: 0;
+}
+.wd-topbar-brand img {
   flex-shrink: 0;
 }
+.wd-topbar-brand span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
 /* Switchers sit right next to the brand (no auto margin here) -
    .wd-topbar-links below is what gets pushed to the far right. */
 .wd-topbar-switchers {
   display: flex;
   align-items: center;
   gap: 0.4rem;
+  flex-shrink: 0;
+}
+.wd-switcher-trigger {
+  white-space: nowrap;
 }
 /* --wd-navbar-border, not --wd-border - falls back to the literal
    var(--wd-border) reference when theme.navbar isn't configured (see
@@ -111,8 +137,88 @@
      visibly above the row's own divider line instead of touching it. */
   align-items: stretch;
   gap: 0.25rem;
+  /* One line, as wide as its tabs: .wd-tabs-viewport shows what fits, and
+     src/scripts/tabs-strip.ts slides the rest into view. */
+  flex: none;
+  width: max-content;
+  position: relative;
+}
+.wd-topbar-tabs > * {
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+.wd-tabs-animate .wd-topbar-tabs {
+  transition: transform 0.25s ease;
+}
+.wd-tabs-strip {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: stretch;
+}
+/* clip, not hidden: `hidden` would make this a scroll container and cut off
+   the tab menus that open below the row. */
+.wd-tabs-viewport {
   flex: 1;
-  flex-wrap: wrap;
+  min-width: 0;
+  display: flex;
+  align-items: stretch;
+  overflow-x: clip;
+  /* Sideways touch moves are src/scripts/tabs-strip.ts's to drag the row;
+     up/down ones still scroll the page. */
+  touch-action: pan-y pinch-zoom;
+}
+/* An arrow on each side that has more tabs, over the row's edge, fading
+   the tab under it out. */
+.wd-tabs-arrow {
+  display: none;
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  z-index: 2;
+  width: 2.5rem;
+  padding: 0;
+  border: none;
+  align-items: center;
+  cursor: pointer;
+  color: var(--wd-navbar-foreground);
+}
+.wd-tabs-arrow-prev {
+  left: 0;
+  justify-content: flex-start;
+  background: linear-gradient(to right, var(--wd-navbar-background) 55%, transparent);
+}
+.wd-tabs-arrow-next {
+  right: 0;
+  justify-content: flex-end;
+  background: linear-gradient(to left, var(--wd-navbar-background) 55%, transparent);
+}
+.wd-tabs-arrow svg {
+  box-sizing: content-box;
+  padding: 0.3rem;
+  border-radius: 999px;
+}
+.wd-tabs-arrow:hover svg {
+  background: var(--wd-navbar-hover);
+}
+.wd-can-prev .wd-tabs-arrow-prev,
+.wd-can-next .wd-tabs-arrow-next {
+  display: flex;
+}
+/* The menu of a tab near the right end opens leftwards, to stay in view. */
+.wd-tabs-strip .wd-dropdown-align-end .wd-dropdown-menu {
+  left: auto;
+  right: 0;
+}
+/* Browsers without overflow-x: clip (Safari before 16): the tabs wrap onto
+   more lines, as before, and the script leaves them alone. */
+@supports not (overflow-x: clip) {
+  .wd-topbar-tabs {
+    flex: 1;
+    width: auto;
+    flex-wrap: wrap;
+  }
 }
 /* .wd-dropdown itself is just a plain block (position: relative, for its
    own .wd-dropdown-menu to anchor to) - stretching *it* to the row's

package/src/lib/canonical-path.js

@@ -0,0 +1,11 @@
+// A Windows path with its drive letter in capitals: `c:\docs` -> `C:\docs`.
+// The same folder can reach writedocs spelled either way (VS Code's
+// terminal often starts in `c:\...`, and a shell prompt in `C:\...`), and
+// Vite compares module ids as text - with the package's own folder spelled
+// `c:`, a build came out with every page missing its stylesheet. Every
+// path the CLI hands Astro goes through this first. Other platforms, and
+// paths without a drive letter, come back unchanged.
+export function canonicalPath(p, platform = process.platform) {
+  if (platform !== 'win32' || typeof p !== 'string') return p;
+  return /^[a-z]:/.test(p) ? p[0].toUpperCase() + p.slice(1) : p;
+}

package/src/lib/config-schema.js

@@ -63,6 +63,7 @@ const dropdownSchema = z.lazy(
 const productSchema = z.lazy(
   () => withChildren({ product: z.string(), icon: z.string().optional(), description: z.string().optional() })
 );
+const MAX_TAB_LEVELS = 2;
 const globalSchema = z.object({ dropdowns: z.array(dropdownSchema).min(1) });
 const navigationSchema = z.union([
   z.array(navItemSchema),
@@ -71,7 +72,39 @@ const navigationSchema = z.union([
   z.object({ global: globalSchema.optional(), languages: z.array(languageSchema).min(1) }).strict(),
   z.object({ global: globalSchema.optional(), dropdowns: z.array(dropdownSchema).min(1) }).strict(),
   z.object({ global: globalSchema.optional(), products: z.array(productSchema).min(1) }).strict()
-]);
+]).superRefine((navigation, ctx) => {
+  const CONTAINERS = ["tabs", "versions", "languages", "dropdowns", "products"];
+  const walk = (node, path, language, tabs) => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return;
+    const own = node;
+    for (const key of CONTAINERS) {
+      const items = own[key];
+      if (!Array.isArray(items)) continue;
+      if (key === "languages" && language !== null) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, key],
+          message: `The language "${language}" contains another "languages" list. A page can only be in one language - put the languages at one level, and the rest (tabs, versions, ...) inside each of them.`
+        });
+        continue;
+      }
+      if (key === "tabs" && tabs.length >= MAX_TAB_LEVELS) {
+        ctx.addIssue({
+          code: "custom",
+          path: [...path, key],
+          message: `Tabs go at most ${MAX_TAB_LEVELS} levels deep, and these are a third level (inside "${tabs.join('" > "')}"). Each level of tabs is a row in the top bar - use a dropdown or groups for this level instead.`
+        });
+        continue;
+      }
+      items.forEach((item, i) => {
+        const inner = key === "languages" ? String(item?.language ?? "") : language;
+        const tab = item?.tab;
+        walk(item, [...path, key, i], inner, key === "tabs" ? [...tabs, String(tab ?? "")] : tabs);
+      });
+    }
+  };
+  walk(navigation, [], null, []);
+});
 const DEFAULT_PRIMARY = "#6366f1";
 const logoSchema = z.union([
   z.string(),
@@ -390,9 +423,28 @@ const apiSchema = z.object({
   // site can set this to `false` to never involve a third party.
   proxy: z.boolean().default(true)
 }).strict().default({ proxy: true });
-const contextMenuSchema = z.object({
-  openIn: z.array(z.enum(["chatgpt", "claude", "perplexity"])).default(["chatgpt", "claude", "perplexity"])
-}).strict();
+const CONTEXT_MENU_OPTIONS = ["copy", "view", "chatgpt", "claude", "perplexity", "mcp", "cursor", "vscode"];
+const ASSISTANT_OPTIONS = ["chatgpt", "claude", "perplexity"];
+const MCP_MENU_OPTIONS = ["mcp", "cursor", "vscode"];
+const contextMenuSchema = z.union([
+  z.boolean(),
+  z.array(z.enum(CONTEXT_MENU_OPTIONS)),
+  z.object({
+    openIn: z.array(z.enum(ASSISTANT_OPTIONS)).optional()
+  }).strict()
+]);
+function contextMenuOptions(value, { mcp = true } = {}) {
+  const available = CONTEXT_MENU_OPTIONS.filter((option) => mcp || !MCP_MENU_OPTIONS.includes(option));
+  if (value === false) return [];
+  if (value === void 0 || value === null || value === true) return [...available];
+  if (Array.isArray(value)) return available.filter((option) => value.includes(option));
+  if (typeof value === "object") {
+    const openIn = value.openIn;
+    const assistants = Array.isArray(openIn) ? openIn : [...ASSISTANT_OPTIONS];
+    return CONTEXT_MENU_OPTIONS.filter((option) => option === "copy" || option === "view" || assistants.includes(option));
+  }
+  return [];
+}
 const redirectSchema = z.object({
   source: z.string(),
   destination: z.string()
@@ -519,8 +571,8 @@ const docsConfigSchema = z.object({
   // field by field via mergeSeo(), rather than needing to repeat every
   // field on every page.
   seo: seoFieldsSchema.default({}),
-  // The "Copy page" dropdown - see contextMenuSchema above. Absent by
-  // default (no menu, no .md routes).
+  // The "Copy page" menu - see contextMenuSchema above. Absent means on,
+  // with every option; read it through contextMenuOptions().
   contextMenu: contextMenuSchema.optional(),
   // The site's MCP server - an AI tool connects to `/mcp` and searches and
   // reads the docs. On by default: `writedocs build` writes the page index
@@ -626,6 +678,62 @@ function desembrulharUnioes(issues, prefixo = []) {
   }
   return saida;
 }
+const LISTAS_DE_CONTAINER = ["tabs", "versions", "languages", "dropdowns", "products"];
+const ITENS_DE_CONTAINER = {
+  tab: { lista: "tabs", nome: "A tab" },
+  version: { lista: "versions", nome: "A version" },
+  language: { lista: "languages", nome: "A language" },
+  dropdown: { lista: "dropdowns", nome: "A dropdown" },
+  product: { lista: "products", nome: "A product" }
+};
+function containersEmPaginas(issues, raiz) {
+  const vistos = /* @__PURE__ */ new Set();
+  const saida = [];
+  for (const issue of issues) {
+    const achado = containerEmPaginas(issue.caminho, raiz);
+    if (!achado) {
+      saida.push(issue);
+      continue;
+    }
+    const chave = achado.caminho.join(".");
+    if (vistos.has(chave)) continue;
+    vistos.add(chave);
+    saida.push({ ...issue, code: "custom", caminho: achado.caminho, message: achado.mensagem, keys: void 0 });
+  }
+  return saida;
+}
+function containerEmPaginas(caminho, raiz) {
+  for (let k = 1; k < caminho.length; k++) {
+    if (typeof caminho[k] !== "number") continue;
+    const naRaiz = k === 1 && caminho[0] === "navigation";
+    if (!naRaiz && caminho[k - 1] !== "pages") continue;
+    const item = valorEm(raiz, caminho.slice(0, k + 1));
+    if (!item || typeof item !== "object" || Array.isArray(item) || "group" in item) continue;
+    const lugar = naRaiz ? "the navigation list" : 'a "pages" list';
+    const rotulo = (texto) => (naRaiz ? "The navigation list" : 'A "pages" list') + ` holds pages, groups and links only. ${texto}`;
+    const lista = LISTAS_DE_CONTAINER.find((l) => l in item);
+    if (lista) {
+      return {
+        caminho: caminho.slice(0, k + 1),
+        mensagem: `"${lista}" can't go inside ${lugar}. ` + rotulo(
+          naRaiz ? `To use ${lista}, make "navigation" an object: "navigation": { "${lista}": [ ... ] }, with the groups inside each of them.` : `Put "${lista}" on "navigation" itself, or on a tab, version, language, dropdown or product in place of its "pages".`
+        )
+      };
+    }
+    const tipo = Object.keys(ITENS_DE_CONTAINER).find((t) => t in item);
+    if (tipo) {
+      const { lista: dela, nome } = ITENS_DE_CONTAINER[tipo];
+      const nomeDoItem = item[tipo];
+      return {
+        caminho: caminho.slice(0, k + 1),
+        mensagem: `${nome}${typeof nomeDoItem === "string" ? ` ("${nomeDoItem}")` : ""} can't go inside ${lugar}. ` + rotulo(
+          naRaiz ? `${nome} goes in a "${dela}" list: "navigation": { "${dela}": [ ... ] }.` : `${nome} goes in a "${dela}" list.`
+        )
+      };
+    }
+  }
+  return null;
+}
 function createJsonLocator(rawText) {
   return criarLocalizador(rawText);
 }
@@ -813,7 +921,7 @@ function validateDocsConfig(rawText) {
       ok: false,
       data: null,
       kind: "schema",
-      issues: desembrulharUnioes(result.error.issues).map((i) => {
+      issues: containersEmPaginas(desembrulharUnioes(result.error.issues), raw).map((i) => {
         const alvoDaLinha = i.code === "unrecognized_keys" && i.keys?.length ? [...i.caminho, i.keys[0]] : i.caminho;
         return {
           path: i.caminho.join(".") || "(root)",
@@ -829,7 +937,11 @@ function validateDocsConfig(rawText) {
   return { ok: true, data: result.data, issues: [] };
 }
 export {
+  CONTEXT_MENU_OPTIONS,
+  MAX_TAB_LEVELS,
+  MCP_MENU_OPTIONS,
   ROOT_ALLOWED_EXTRA_KEYS,
+  contextMenuOptions,
   createJsonLocator,
   docsConfigSchema,
   formatValidationIssues,