@writedocs/generator 0.9.1 → 0.9.3

package/package.json

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

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

@@ -14,7 +14,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const REFRESH = /<meta http-equiv="refresh" content="0;url=([^"]*)"\s*\/?>/i;
+// 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;
 

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/layout/BaseLayout.astro

@@ -566,6 +566,10 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         --wd-text-muted: #64748b;
         --wd-border: #e2e8f0;
         --wd-surface: #f8fafc;
+        /* The browser's own controls - the page's scrollbar, a code block's -
+           drawn for the theme on screen. Without it they stayed light in dark
+           mode. */
+        color-scheme: light;
         /* Not mode-dependent (a site's chosen font doesn't change between
            light/dark) - set once here rather than duplicated in the
            :root[data-theme='dark'] block below. */
@@ -594,6 +598,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         --wd-text-muted: #94a3b8;
         --wd-border: #1e293b;
         --wd-surface: #131a2b;
+        color-scheme: dark;
       }
     </style>
     {/* styles.fonts: local/externally-hosted font(s) (fontFaceRule() in

package/src/layout/styles/base.css

@@ -244,3 +244,47 @@ img.wd-icon-img {
   height: 1em;
   object-fit: contain;
 }
+
+/* Scrollbars of the columns beside the page - the sidebar, the table of
+   contents, the mobile menu and its option lists: a thin pill in the
+   site's muted text color on no track, faint while the pointer is
+   elsewhere, clearer over the column, strongest on the pill itself.
+   Chromium and Safari draw it from the ::-webkit-scrollbar rules (the
+   standard scrollbar-color/-width would switch those off in Chromium, and
+   can't make it this thin); Firefox, which has only the standard ones,
+   gets its thin scrollbar in the same colors. */
+:root {
+  --wd-scrollbar-thumb: color-mix(in srgb, var(--wd-text-muted) 22%, transparent);
+  --wd-scrollbar-thumb-near: color-mix(in srgb, var(--wd-text-muted) 45%, transparent);
+  --wd-scrollbar-thumb-active: color-mix(in srgb, var(--wd-text-muted) 70%, transparent);
+}
+:is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel)::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+:is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel)::-webkit-scrollbar-track {
+  background: transparent;
+}
+:is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel)::-webkit-scrollbar-thumb {
+  background: var(--wd-scrollbar-thumb);
+  /* A 6px pill with 2px of air on each side - off the column's border line. */
+  border: 2px solid transparent;
+  background-clip: padding-box;
+  border-radius: 999px;
+}
+:is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel):hover::-webkit-scrollbar-thumb {
+  background: var(--wd-scrollbar-thumb-near);
+}
+:is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel)::-webkit-scrollbar-thumb:hover,
+:is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel)::-webkit-scrollbar-thumb:active {
+  background: var(--wd-scrollbar-thumb-active);
+}
+@supports not selector(::-webkit-scrollbar) {
+  :is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel) {
+    scrollbar-width: thin;
+    scrollbar-color: var(--wd-scrollbar-thumb) transparent;
+  }
+  :is(.wd-sidebar, .wd-toc, .wd-mobile-menu-scroll, .wd-mobile-accordion-options-panel):hover {
+    scrollbar-color: var(--wd-scrollbar-thumb-near) transparent;
+  }
+}

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

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/pages/[...slug].astro

@@ -158,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
@@ -259,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;
@@ -274,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,