@writedocs/generator 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/build.js

@@ -6,6 +6,8 @@ import { runPagefind } from './run-pagefind.js';
 import { preflightCheck, sameDriveCheck, writableInstallCheck } from './preflight.js';
 import { generateApiPages } from './generate-api-pages.js';
 import { writeRedirectsFile } from './write-redirects-file.js';
+import { rewriteRedirectPages } from './rewrite-redirect-pages.js';
+import { readConfigText } from '../lib/config-file.js';
 import { writeMcpFiles } from './write-mcp-files.js';
 import { pagesWithoutStyles } from './check-built-styles.js';
 import { writedocsBuildStagingDir } from '../lib/writedocs-temp-dir.js';
@@ -128,6 +130,10 @@ export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   // - this turns those into real instant edge redirects on hosts that read
   // a `_redirects` file (Cloudflare Pages, Netlify), purely additively.
   writeRedirectsFile(distDir, contentDir);
+  // Every other host follows Astro's redirect pages - rewritten so the
+  // reader never sees one (rewrite-redirect-pages.js).
+  const siteConfig = JSON.parse(readConfigText(contentDir));
+  rewriteRedirectPages(distDir, { background: siteConfig.styles?.background?.colors });
   // The site's MCP server at /mcp: mcp-index.json is already in dist/ (an
   // Astro route); this adds the Cloudflare _worker.js that serves it - see
   // write-mcp-files.js for every host.

package/src/cli/rewrite-redirect-pages.js

@@ -0,0 +1,85 @@
+// Astro's static build writes every redirect - the site's `/` when no page
+// sits there, and writedocs.json's `redirects` - as a page with a 0-second
+// <meta http-equiv="refresh">. That page has no styles: the browser paints
+// it (white, with a "Redirecting from / to ..." link) before following the
+// refresh - a visible flash on every host that doesn't redirect at the edge
+// (Cloudflare Pages and Netlify do, from _redirects - write-redirects-file.js).
+//
+// After the build, each of those pages is rewritten so there's nothing to
+// see: a script at the top of <head> redirects before anything is painted
+// (keeping the query string and #anchor, which a meta refresh drops), the
+// page is the site's own background color in the reader's theme, and the
+// link is there for screen readers and as the no-script fallback, not on
+// screen. The meta refresh stays for browsers without JavaScript.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Any delay: Astro waits 2 seconds on a 302's page (the automatic "/"), none on a 301's.
+const REFRESH = /<meta http-equiv="refresh" content="\d+;\s*url=([^"]*)"\s*\/?>/i;
+const ASTRO_REDIRECT = /<title>Redirecting to:/;
+const CANONICAL = /<link rel="canonical" href="([^"]*)"\s*\/?>/i;
+
+const DEFAULT_LIGHT = '#ffffff';
+const DEFAULT_DARK = '#0b1120';
+
+function decodeAttr(value) {
+  return value.replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+}
+function encodeAttr(value) {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** A color from writedocs.json, only if it's safe inside a <style>. */
+function cssColor(value, fallback) {
+  return typeof value === 'string' && /^[#a-zA-Z0-9(),.%\s-]{1,64}$/.test(value) ? value : fallback;
+}
+
+/** The page for a redirect to `target`. */
+export function redirectPageHtml({ target, canonical = null, background = {} }) {
+  const light = cssColor(background.light, DEFAULT_LIGHT);
+  const dark = cssColor(background.dark, DEFAULT_DARK);
+  // Inside <script>: a JSON string, with "<" escaped so a target can't end the script.
+  const js = JSON.stringify(target).replace(/</g, '\\u003c');
+  const attr = encodeAttr(target);
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    `<script>location.replace(${js} + location.search + location.hash)</script>`,
+    `<meta http-equiv="refresh" content="0;url=${attr}">`,
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<meta name="robots" content="noindex">',
+    canonical ? `<link rel="canonical" href="${encodeAttr(canonical)}">` : '',
+    '<title>Redirecting…</title>',
+    // Same theme choice as every page (BaseLayout.astro): the stored one, else the system's.
+    "<script>try{var t=localStorage.getItem('wd-theme');if(t!=='light'&&t!=='dark')t=matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.dataset.theme=t}catch(e){}</script>",
+    `<style>html{background:${light};color-scheme:light}html[data-theme=dark]{background:${dark};color-scheme:dark}@media (prefers-color-scheme:dark){html:not([data-theme]){background:${dark};color-scheme:dark}}body{margin:0}a{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap}</style>`,
+    '</head>',
+    `<body><a href="${attr}">Continue to ${attr}</a></body>`,
+    '</html>',
+    '',
+  ].filter(Boolean).join('\n');
+}
+
+/** Rewrites every Astro redirect page under `distDir`. Returns how many. */
+export function rewriteRedirectPages(distDir, { background } = {}) {
+  let count = 0;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== '_astro' && entry.name !== 'pagefind') walk(full);
+        continue;
+      }
+      if (!entry.name.endsWith('.html')) continue;
+      const html = fs.readFileSync(full, 'utf8');
+      const refresh = REFRESH.exec(html);
+      if (!refresh || !ASTRO_REDIRECT.test(html)) continue;
+      const canonical = CANONICAL.exec(html);
+      fs.writeFileSync(full, redirectPageHtml({ target: decodeAttr(refresh[1]), canonical: canonical ? decodeAttr(canonical[1]) : null, background }));
+      count++;
+    }
+  };
+  walk(distDir);
+  return count;
+}

package/src/cli/write-redirects-file.js

@@ -58,7 +58,9 @@ export function writeRedirectsFile(distDir, contentDir) {
   if (!hasExplicitRootRedirect && fs.existsSync(indexHtmlPath)) {
     const html = fs.readFileSync(indexHtmlPath, 'utf8');
     const match = html.match(/<meta http-equiv="refresh" content="\d+;\s*url=([^"]+)"/i);
-    if (match) lines.push(`/ ${match[1]} 301`);
+    // 302, not 301: see [...slug].astro - a browser keeps a 301 for good,
+    // and "/" stops redirecting once the site gets a home page.
+    if (match) lines.push(`/ ${match[1]} 302`);
   }
 
   if (lines.length === 0) return;

package/src/components/CopyPageMenu.astro

@@ -210,6 +210,9 @@ const hasDropdown = items.length > 0 && !single;
     border: 1px solid var(--wd-border);
     border-radius: 0.4rem;
     flex-shrink: 0;
+    /* Right-aligned on its own line too (a long title on a phone sends it
+       below the title) - its menu opens leftwards, and stays on screen. */
+    margin-left: auto;
   }
   /* .wd-copy-page is this instance's own class on the .wd-dropdown div
      wrapping the caret button + menu (see BaseLayout.astro's shared

package/src/layout/components/MobileMenu.astro

@@ -31,6 +31,7 @@
 // comment for the fuller rationale.
 import { isExternalHref, type DocsConfig, type Selector, type GlobalDropdownView } from '../../lib/config';
 import AppIcon from '../../components/AppIcon.astro';
+import { hasMobileMenu } from '../../lib/selector-placement.js';
 import '../styles/dropdown.css';
 import '../styles/topbar.css';
 import '../styles/mobile-menu.css';
@@ -48,8 +49,11 @@ interface Props {
   brandLabel?: string;
 }
 const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark, brandLabel } = Astro.props as Props;
+// A page without a sidebar (`mode: custom`) still gets the menu when it has
+// tabs, switchers or global dropdowns to reach - just without the sidebar part.
+const showMenu = hasMobileMenu({ sidebar: showSidebarCol, selectors, globalDropdowns });
 ---
-{showSidebarCol && (
+{showMenu && (
   <div class="wd-mobile-menu" id="wd-mobile-menu" inert>
     <div class="wd-mobile-menu-backdrop" data-mobile-menu-backdrop></div>
     <div class="wd-mobile-menu-panel" role="dialog" aria-modal="true" aria-label="Navigation">
@@ -171,9 +175,11 @@ const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark,
             )}
           </div>
         )}
-        <div class="wd-mobile-menu-sidebar">
-          <slot name="sidebar" />
-        </div>
+        {showSidebarCol && (
+          <div class="wd-mobile-menu-sidebar">
+            <slot name="sidebar" />
+          </div>
+        )}
       </div>
     </div>
   </div>

package/src/layout/components/Sidebar.astro

@@ -1,6 +1,7 @@
 ---
-import type { NavTreeNode } from "../../lib/config";
+import { isExternalHref, type NavTreeNode, type Selector } from "../../lib/config";
 import NavTree from "./NavTree.astro";
+import AppIcon from "../../components/AppIcon.astro";
 // Two colorways of the same "Powered by writedocs" mark, not a
 // theme-matched pair in the wd-logo-light/wd-logo-dark sense (that
 // convention names each file by which theme it's *shown in*) - these
@@ -32,11 +33,50 @@ interface Props {
   navTree: NavTreeNode[];
   hrefForSlug: (slug: string) => string;
   currentSlug: string;
+  // Switchers that sit at the top of the sidebar instead of the top bar -
+  // products inside a tab or dropdown (lib/selector-placement.js).
+  switchers?: Selector[];
 }
-const { navTree, hrefForSlug, currentSlug } = Astro.props as Props;
+const { navTree, hrefForSlug, currentSlug, switchers = [] } = Astro.props as Props;
 ---
 
 <nav class="wd-sidebar">
+  {switchers.map((sel) => {
+    const current = sel.options.find((o) => o.active) ?? sel.options[0];
+    return (
+      <div class="wd-dropdown wd-sidebar-switcher" data-selector-kind={sel.kind}>
+        <button type="button" class="wd-dropdown-trigger wd-sidebar-switcher-trigger" aria-expanded="false">
+          <AppIcon icon={current.icon} class="wd-tab-icon wd-sidebar-switcher-icon" />
+          <span class="wd-sidebar-switcher-text">
+            <span class="wd-sidebar-switcher-label">{current.label}</span>
+            {current.description && <span class="wd-sidebar-switcher-desc">{current.description}</span>}
+          </span>
+          <svg class="wd-sidebar-switcher-chevrons" width="12" height="12" viewBox="0 0 12 12" aria-hidden="true">
+            <path d="M3.5 4.5L6 2L8.5 4.5M3.5 7.5L6 10L8.5 7.5" stroke="currentColor" stroke-width="1.3" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+          </svg>
+        </button>
+        <div class="wd-dropdown-menu wd-sidebar-switcher-menu">
+          <div class="wd-dropdown-menu-panel">
+            {sel.options.map((opt) => (
+              <a
+                href={opt.href}
+                class={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 wd-sidebar-switcher-icon" />
+                <span class="wd-sidebar-switcher-text">
+                  <span class="wd-sidebar-switcher-label">{opt.label}</span>
+                  {opt.description && <span class="wd-sidebar-switcher-desc">{opt.description}</span>}
+                </span>
+              </a>
+            ))}
+          </div>
+        </div>
+      </div>
+    );
+  })}
   <NavTree nodes={navTree} hrefForSlug={hrefForSlug} currentSlug={currentSlug} />
   {!watermarkDisabled && (
     <div class="wd-sidebar-watermark">
@@ -46,6 +86,74 @@ const { navTree, hrefForSlug, currentSlug } = Astro.props as Props;
   )}
 </nav>
 <style>
+  /* The product switcher at the top of the sidebar - Mintlify's place for
+     it. Full width, the current product (and its description) on the
+     button, every product in the menu. It opens on click only: the shared
+     hover-to-open (dropdown.css) would pop it open every time the pointer
+     crosses the sidebar. */
+  .wd-sidebar-switcher {
+    margin-bottom: 1rem;
+  }
+  .wd-sidebar-switcher-trigger {
+    width: 100%;
+    box-sizing: border-box;
+    gap: 0.6rem;
+    padding: 0.5rem 0.65rem;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.5rem;
+    color: var(--wd-text);
+    text-align: left;
+  }
+  .wd-sidebar-switcher-trigger:hover {
+    background: var(--wd-surface);
+  }
+  .wd-sidebar-switcher-text {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-width: 0;
+  }
+  .wd-sidebar-switcher-label {
+    font-size: 0.88rem;
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .wd-sidebar-switcher-desc {
+    font-size: 0.75rem;
+    font-weight: 400;
+    color: var(--wd-text-muted);
+  }
+  .wd-sidebar-switcher-trigger .wd-sidebar-switcher-desc {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .wd-sidebar-switcher-chevrons {
+    flex-shrink: 0;
+    color: var(--wd-text-muted);
+  }
+  .wd-sidebar-switcher:not(.open) .wd-sidebar-switcher-menu {
+    display: none;
+  }
+  .wd-sidebar-switcher-menu {
+    right: 0;
+  }
+  .wd-sidebar-switcher-menu .wd-dropdown-menu-panel {
+    min-width: 0;
+  }
+  .wd-sidebar-switcher-menu a {
+    align-items: flex-start;
+  }
+  .wd-sidebar-switcher-menu .wd-sidebar-switcher-icon {
+    margin-top: 0.2rem;
+  }
+  /* The mobile menu already lists every level as its own row above the
+     sidebar - no second copy there. */
+  :global(#wd-mobile-menu) .wd-sidebar-switcher {
+    display: none;
+  }
   /* Sticky + its own scrollbar, not just "moves along until it runs out
      of column to stick within" (position: sticky's default behavior,
      which is what this had before - a tall nav tree would eventually

package/src/layout/components/TopBar.astro

@@ -13,6 +13,7 @@
 // comment for the fuller rationale.
 import { isExternalHref, type DocsConfig, type Selector, type GlobalDropdownView } from '../../lib/config';
 import AppIcon from '../../components/AppIcon.astro';
+import { selectorPlacements, hasMobileMenu } from '../../lib/selector-placement.js';
 import '../styles/dropdown.css';
 import '../styles/topbar.css';
 
@@ -52,9 +53,12 @@ const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark,
 // switcher), this one is dropped from switcherSelectors entirely -
 // `selectors` is in root-to-leaf path order, so "nested directly inside a
 // tab" just means the previous entry in the array is the 'tab' selector.
-const switcherSelectors = selectors.filter(
-  (sel, i) => sel.kind !== 'tab' && !(sel.kind === 'dropdown' && selectors[i - 1]?.kind === 'tab')
-);
+// Which level goes where - lib/selector-placement.js. A product inside a tab
+// or dropdown sits at the top of the sidebar instead (Sidebar.astro), when
+// the page has one.
+const placements = selectorPlacements(selectors, { sidebar: showSidebarCol });
+const showMenuButton = hasMobileMenu({ sidebar: showSidebarCol, selectors, globalDropdowns });
+const switcherSelectors = selectors.filter((_, i) => placements[i] === 'topbar');
 const tabSelectors = selectors.filter((sel) => sel.kind === 'tab');
 // 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
@@ -64,12 +68,13 @@ const tabRows = tabSelectors.length > 0 ? tabSelectors : globalDropdowns.length
 <header class="wd-topbar">
   <div class="wd-topbar-row wd-topbar-row-brand">
     <div class="wd-topbar-inner">
-      {/* Only rendered on pages that would show a sidebar at all
-          (showSidebarCol - same condition MobileMenu.astro's own
-          rendering is gated on). Hidden entirely above 860px via CSS
-          (.wd-mobile-menu-toggle's own media query in topbar.css), not
-          JS - so there's no flash-of-hamburger on a desktop-width load. */}
-      {showSidebarCol && (
+      {/* Only rendered on pages that have a mobile menu - a sidebar, or
+          navigation the top bar hides on a phone (hasMobileMenu(), the same
+          condition MobileMenu.astro's own rendering is gated on). Hidden
+          entirely above 860px via CSS (.wd-mobile-menu-toggle's own media
+          query in topbar.css), not JS - so there's no flash-of-hamburger on
+          a desktop-width load. */}
+      {showMenuButton && (
         <button
           type="button"
           class="wd-mobile-menu-toggle"

package/src/layout/styles/mobile-menu.css

@@ -146,6 +146,12 @@
   padding-bottom: 0.75rem;
   border-bottom: 1px solid var(--wd-border);
 }
+/* A page without a sidebar (`mode: custom`): nothing below to divide off. */
+.wd-mobile-menu-selectors:last-child {
+  margin-bottom: 0;
+  padding-bottom: 0;
+  border-bottom: none;
+}
 /* position: relative makes this the containing block for its own
    .wd-mobile-accordion-options panel below, which floats over whatever
    comes after it instead of pushing it down the page - a `<details>`'s

package/src/layout/styles/topbar.css

@@ -523,4 +523,10 @@
   .wd-mobile-menu-toggle {
     display: flex;
   }
+  /* The site name takes what's left of the row and ends in "..." when it
+     doesn't fit - otherwise a long name wraps onto a row of its own and the
+     top bar grows to three rows. */
+  .wd-topbar-brand {
+    flex: 1 1 0;
+  }
 }

package/src/lib/config.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { EXCLUDED_TOP_LEVEL_DIRS } from './pages.js';
+import { EXCLUDED_TOP_LEVEL_DIRS, navPageId } from './pages.js';
 import matter from 'gray-matter';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 import { readableTextOn } from './color.js';
@@ -419,10 +419,27 @@ export function loadDocsConfig(contentDir: string): DocsConfig {
   // A no-op pass over ordinary navigation trees (no openapi groups) -
   // always run, rather than gated behind a global manifest check, since
   // there's no longer a single global spec to check for.
-  result.data.navigation = expandOpenApiInNavigation(result.data.navigation, contentDir);
+  result.data.navigation = withPageIds(expandOpenApiInNavigation(result.data.navigation, contentDir));
   return result.data;
 }
 
+/** The navigation with every page entry as its page id - "guides/index"
+ *  becomes "guides" (navPageId() in lib/pages.js), so everything that
+ *  matches entries against pages (routes, the sidebar, prev/next, llms.txt,
+ *  the MCP index) finds a folder's index.mdx however writedocs.json names it. */
+function withPageIds<T>(node: T): T {
+  if (Array.isArray(node)) return node.map((item) => (typeof item === 'string' ? navPageId(item) : withPageIds(item))) as T;
+  if (node && typeof node === 'object') {
+    return Object.fromEntries(
+      Object.entries(node).map(([key, value]) => [
+        key,
+        key === 'page' && typeof value === 'string' ? navPageId(value) : key === 'href' || key === 'openapi' ? value : withPageIds(value),
+      ])
+    ) as T;
+  }
+  return node;
+}
+
 // --- Locating a page by file id, independent of its effective slug -----
 //
 // writedocs.json's `pages` arrays, and every helper above/below that walks
@@ -909,6 +926,9 @@ export interface SelectorOption {
   label: string;
   icon?: string;
   tag?: string;
+  // A product's `description` - shown under its name where there's room
+  // (the sidebar's product switcher, see lib/selector-placement.js).
+  description?: string;
   href: string;
   active: boolean;
   // Set when this option's own container is a `dropdowns` list (e.g. a
@@ -976,6 +996,7 @@ export function buildSelectors(
           label: labelOf(item),
           icon: iconOf(item),
           tag: 'tag' in item ? item.tag : undefined,
+          description: 'description' in item ? item.description : undefined,
           href: 'href' in item ? item.href : hrefForSlug(targetSlug),
           active: isActive,
           dropdown: dropdownMenuOf(item, hrefForSlug, isActive ? path[segIndex + 1] : undefined),

package/src/lib/content-check.js

@@ -30,7 +30,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
 import { visit } from 'unist-util-visit';
-import { findAllPages, fileIdForPath, titleFromPath } from './pages.js';
+import { findAllPages, fileIdForPath, titleFromPath, navPageId } from './pages.js';
 import { iconExists } from './icons.js';
 import { findUnknownComponents } from './mdx-unknown-components.js';
 import { findInteractiveComponents, simplifiedBuiltinMessage } from './mdx-inline-react.js';
@@ -400,16 +400,14 @@ export async function checkContent(contentDir, configText) {
     const locate = createJsonLocator(configText);
     const ids = new Set(pages.map(fileIdForPath));
     for (const ref of navigationReferences(config.navigation)) {
-      if (ids.has(ref.id)) continue;
-      const folderIndex = ref.id.endsWith('/index') && ids.has(ref.id.replace(/\/index$/, ''));
+      // "guides/index" and "guides" both name guides/index.mdx (navPageId()).
+      if (ids.has(navPageId(ref.id))) continue;
       errors.push(
         issue(
           'writedocs.json',
           locate(ref.path)?.line,
           `The navigation lists page "${ref.id}", but there's no page with that path.`,
-          folderIndex
-            ? `A folder's index page is listed by the folder's path - write "${ref.id.replace(/\/index$/, '')}".`
-            : `Create ${ref.id}.mdx, or fix the path (it's relative to the folder writedocs.json is in, without the extension).`
+          `Create ${ref.id}.mdx, or fix the path (it's relative to the folder writedocs.json is in, without the extension).`
         )
       );
     }

package/src/lib/pages.js

@@ -16,9 +16,16 @@ export const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro'
 /** A page's title when its frontmatter has none - Mintlify's rule, so a
  *  migrated page that relied on it keeps the same title: the file name
  *  without its extension, dashes and underscores as spaces, first letter
- *  capitalized. `guides/getting-started.mdx` -> "Getting started". */
+ *  capitalized. `guides/getting-started.mdx` -> "Getting started". A
+ *  folder's index page is named for the folder (`api/index.mdx` -> "Api"),
+ *  and the site's own index.mdx is "Home" - "Index" names neither. */
 export function titleFromPath(filePath) {
-  const base = String(filePath).split(/[\\/]/).pop().replace(/\.mdx?$/i, '');
+  const parts = String(filePath).split(/[\\/]/).filter(Boolean);
+  let base = (parts.pop() ?? '').replace(/\.mdx?$/i, '');
+  if (base.toLowerCase() === 'index') {
+    if (parts.length === 0) return 'Home';
+    base = parts.pop();
+  }
   const words = base.replace(/[-_]+/g, ' ').trim();
   return words ? words.charAt(0).toUpperCase() + words.slice(1) : 'Untitled';
 }
@@ -61,15 +68,23 @@ function readIgnoreFile(contentDir) {
  *  groups' `page`) - read straight from the file, since this runs before
  *  (and independently of) config validation. Empty when there's no
  *  readable writedocs.json. */
+/** The page id a navigation entry names. "guides/index" and "guides" are
+ *  the same page: a folder's index.mdx has the folder's id (fileIdForPath()
+ *  below), and Mintlify projects write it either way. The root "index"
+ *  stays as it is. */
+export function navPageId(id) {
+  return id.endsWith('/index') ? id.slice(0, -'/index'.length) : id;
+}
+
 /** Every page id a `navigation` lists, in the order a reader meets them -
  *  top to bottom, each group's own `page` before its `pages` - without
  *  repeats. */
 export function navigationPageOrder(navigation) {
   const ids = new Set();
   (function walk(node) {
-    if (Array.isArray(node)) node.forEach((item) => (typeof item === 'string' ? ids.add(item) : walk(item)));
+    if (Array.isArray(node)) node.forEach((item) => (typeof item === 'string' ? ids.add(navPageId(item)) : walk(item)));
     else if (node && typeof node === 'object') {
-      if (typeof node.page === 'string') ids.add(node.page);
+      if (typeof node.page === 'string') ids.add(navPageId(node.page));
       for (const [key, value] of Object.entries(node)) {
         if (key !== 'page' && key !== 'openapi' && key !== 'href') walk(value);
       }

package/src/lib/selector-placement.js

@@ -0,0 +1,30 @@
+// Where each level of a page's navigation path shows its switcher - one
+// entry per Selector (buildSelectors() in lib/config.ts), root first:
+//
+//   'tabs'      a row of tabs in the top bar (a second row for tabs inside tabs)
+//   'tab-menu'  the menu of the tab it sits in (dropdowns directly inside a tab)
+//   'sidebar'   the top of the sidebar: products inside a tab or a dropdown,
+//               like Mintlify's - they pick what the sidebar shows
+//   'topbar'    a switcher next to the site name (everything else)
+//
+// Without a sidebar on the page (`mode: custom` / `blank`), a 'sidebar'
+// switcher goes to the top bar instead. The mobile menu lists every level
+// either way.
+
+export function selectorPlacements(selectors, { sidebar = true } = {}) {
+  return selectors.map((sel, i) => {
+    const parent = selectors[i - 1]?.kind;
+    if (sel.kind === 'tab') return 'tabs';
+    if (sel.kind === 'dropdown' && parent === 'tab') return 'tab-menu';
+    if (sel.kind === 'product' && (parent === 'tab' || parent === 'dropdown')) return sidebar ? 'sidebar' : 'topbar';
+    return 'topbar';
+  });
+}
+
+/** Whether a page gets the mobile menu (its button in the top bar, and the
+ *  panel - TopBar.astro and MobileMenu.astro both ask this). On a phone the
+ *  top bar hides the tabs and switchers, so any page with navigation to
+ *  reach needs it - with a sidebar or without (`mode: custom`). */
+export function hasMobileMenu({ sidebar, selectors = [], globalDropdowns = [] }) {
+  return sidebar || selectors.length > 0 || globalDropdowns.length > 0;
+}

package/src/pages/[...slug].astro

@@ -70,6 +70,7 @@ import { Tree, FileTree, Color, GitHub } from "../components/compound";
 import ApiPlayground from "../components/ApiPlayground.astro";
 import ApiReferencePanel from "../components/ApiReferencePanel.astro";
 import { searchScope, sectionTrail, ALL_SCOPES } from "../lib/search-scope.js";
+import { selectorPlacements } from "../lib/selector-placement.js";
 
 // A page is hand-written (the `pages` collection, sourced from anywhere
 // in the project - docs/ has no special status, see findAllPages() in
@@ -157,7 +158,7 @@ export async function getStaticPaths() {
   // rootAlreadyClaimed rules out), so the ternary below always resolves
   // to the non-root branch.
   const rootRedirect = firstEntry
-    ? [{ params: { slug: undefined }, props: { redirectTo: `/${normalizeEntryId(firstEntry.id)}/` } }]
+    ? [{ params: { slug: undefined }, props: { redirectTo: `/${normalizeEntryId(firstEntry.id)}/`, temporary: true } }]
     : [];
 
   // Tracks every file id a nav-driven route below already claims, so
@@ -258,6 +259,8 @@ export async function getStaticPaths() {
 
 interface Props {
   redirectTo?: string;
+  // The automatic "/" redirect: temporary, see below.
+  temporary?: boolean;
   entry?: DocsEntry;
   prev?: { slug: string; group: string | null } | null;
   next?: { slug: string; group: string | null } | null;
@@ -273,11 +276,15 @@ interface Props {
 
 const rawProps = Astro.props as Props;
 if (rawProps.redirectTo) {
-  // 301, not Astro's default 302: in a static build the status only picks
-  // the meta refresh delay (astro/dist/core/routing/3xx.js) - 2 seconds of
-  // "Redirecting from..." text for a 302, none for a 301. Hosts that read
-  // _redirects get a real 301 for "/" too (write-redirects-file.js).
-  return Astro.redirect(rawProps.redirectTo, 301);
+  // The automatic "/" redirect is temporary (302): its target is just the
+  // navigation's first page, and it goes away once the site has a page at
+  // "/". A 301 is remembered by the browser for good - after that, "/" kept
+  // redirecting even with a home page in place, in `writedocs dev` (every
+  // project's preview shares localhost:4321) and for returning visitors.
+  // A frontmatter `url` page stays 301. In a static build the status only
+  // picks the refresh delay of Astro's redirect page, and the build rewrites
+  // those pages to redirect at once either way (rewrite-redirect-pages.js).
+  return Astro.redirect(rawProps.redirectTo, rawProps.temporary ? 302 : 301);
 }
 const {
   entry,
@@ -413,6 +420,10 @@ const currentPath = hrefForSlug(currentFileId);
 // it set one explicitly, still wins.
 const pageMode = isHidden && entry.data.mode === "default" ? "frame" : entry.data.mode;
 const showSidebar = pageMode === "default" || pageMode === "wide";
+// Products inside a tab or dropdown switch at the top of the sidebar, not in
+// the top bar (lib/selector-placement.js - TopBar.astro applies the same rule).
+const sidebarPlacements = selectorPlacements(selectors, { sidebar: showSidebar });
+const sidebarSwitchers = selectors.filter((_, i) => sidebarPlacements[i] === "sidebar");
 const showToc = pageMode === "default";
 // 'custom' and 'blank' both get the bare wd-canvas treatment below (no
 // auto <h1>, no prev/next, no prose width/padding) - they only differ in
@@ -493,7 +504,7 @@ const components = {
   mode={pageMode}
   lang={pageLang}
 >
-  {showSidebar && <Sidebar slot="sidebar" navTree={navTree} hrefForSlug={hrefForSlug} currentSlug={currentFileId} />}
+  {showSidebar && <Sidebar slot="sidebar" navTree={navTree} hrefForSlug={hrefForSlug} currentSlug={currentFileId} switchers={sidebarSwitchers} />}
   {
     isCanvasMode ? (
       // 'custom' and 'blank' both get this treatment: no auto <h1>, no
@@ -923,13 +934,25 @@ const components = {
      direct .wd-article child. */
   .wd-article-header {
     display: flex;
+    flex-wrap: wrap;
     align-items: center;
     justify-content: space-between;
-    gap: 1rem;
+    gap: 0.75rem 1rem;
     margin: 0 0 1rem;
   }
   .wd-article-header h1 {
     margin: 0;
+    /* A word longer than the whole line (a long product name on a phone)
+       breaks rather than pushing the page wider than the screen. */
+    overflow-wrap: break-word;
+  }
+  /* The title takes the room the menu leaves. Its basis is 0, so the row
+     only wraps when its longest word and the menu can't share a line - on
+     a desktop, a long title still wraps beside the menu; on a phone, a long
+     word sends the menu below the title instead of off the screen. */
+  .wd-article-header > h1,
+  .wd-article-header > .wd-article-title {
+    flex: 1 1 0;
   }
   /* Frontmatter `deprecated: true` (Mintlify's) - same amber as the
      sidebar's own deprecated tag (NavTree.astro) and Parameter's