docs: sync theme, fix downloads, expand guide content, other fixes

Syncs Scalar theme with Neon's dark/light toggle, points the OpenAPI
download at the upstream spec, and adds a getting-started primer plus
tag intros for the core resources. Empty tags now hidden.

Author: philip

src/app/(api-docs)/docs/api-reference-preview/ScalarMount.tsx

@@ -1,21 +1,18 @@
 'use client';
 
-import { useTheme } from 'next-themes';
 import { useEffect, useRef } from 'react';
 
-// Pin to major version so patch/minor updates are picked up but breaking changes are not.
-// Update this when intentionally upgrading Scalar.
+// Pin to major so patch/minor updates flow but breaking changes don't.
+// Update when intentionally upgrading Scalar.
 const CDN_URL = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1';
 
-// Module-level promise: CDN loads once per page session regardless of React re-renders or
-// theme changes. Persists across HMR reloads in dev (acceptable).
+// Module-level: CDN loads once per page session regardless of remounts.
 let scalarCdnReady: Promise<void> | null = null;
 
 function loadScalarCdn(): Promise<void> {
   if (scalarCdnReady) return scalarCdnReady;
 
   scalarCdnReady = new Promise((resolve, reject) => {
-    // Already loaded (e.g. back-navigation in SPA)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     if (typeof (window as any).Scalar?.createApiReference === 'function') {
       resolve();
@@ -34,11 +31,37 @@ function loadScalarCdn(): Promise<void> {
   return scalarCdnReady;
 }
 
-function buildConfig(spec: string, darkMode: boolean) {
+// Factory for a Scalar fetch interceptor. When Scalar asks for `specUrl`, return our
+// pre-mutated spec. Any other URL (e.g. external $refs) falls through to real fetch.
+// New Response per call — Response bodies are one-shot and Scalar may re-read.
+function createSpecFetch(specUrl: string, specBody: string) {
+  return async (url: string): Promise<Response> => {
+    if (url === specUrl) {
+      return new Response(specBody, {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return fetch(url);
+  };
+}
+
+function buildConfig(spec: string, specUrl: string, darkMode: boolean) {
   return {
-    content: spec,
+    // Pass `url` (not `content`) so Scalar's workspace store populates
+    // document.x-scalar-original-source-url with specUrl — which is what the
+    // "Download OpenAPI Document" link reads in `direct` mode. The interceptor
+    // below makes Scalar fetch our mutated spec from that URL instead of the wire.
+    url: specUrl,
+    fetch: createSpecFetch(specUrl, spec),
     theme: 'default',
     darkMode,
+    // Makes Scalar's initial body.dark-mode/.light-mode class match Neon's theme on
+    // first mount. Scalar's useColorMode reads this once at init and is not reactive
+    // to later updateConfiguration calls — subsequent theme changes are handled by
+    // the MutationObserver + CSS keyed on html.dark.
+    forceDarkModeState: darkMode ? 'dark' : 'light',
+    // Neon's header is the single source of truth for theme.
+    hideDarkModeToggle: true,
     agent: { disabled: true },
     mcp: { disabled: true },
     showDeveloperTools: 'never',
@@ -47,21 +70,43 @@ function buildConfig(spec: string, darkMode: boolean) {
     hideTestRequestButton: true,
     defaultOpenAllTags: true,
     defaultHttpClient: { targetKey: 'shell', clientKey: 'curl' },
+    // 'direct' points the download button at specUrl itself (real, unmutated spec on
+    // neon.com). Other values ('json'|'yaml'|'both') would serialize our in-memory
+    // mutated spec and leak injected guide markdown into the downloaded file.
+    documentDownloadType: 'direct',
   };
 }
 
 const NEON_CSS = `
-  /* --scalar-custom-header-height is Scalar's public variable for external header height.
-     It feeds --refs-header-height which controls sidebar sticky top, sidebar height,
-     and IntersectionObserver rootMargin. Must be set on :root. */
+  /* Scalar's public var for external header offset. Feeds --refs-header-height which
+     controls sidebar sticky top, sidebar height, and IntersectionObserver rootMargin. */
   :root {
     --scalar-custom-header-height: 112px;
   }
-  /* Ensure anchor jumps and sidebar scrollIntoView land below the Neon header */
   html {
     scroll-padding-top: 112px;
   }
-  #scalar-mount .dark-mode {
+  /* Hide the right-column quickstart panel on the info block (server URL + Client
+     Libraries snippet). It duplicates info we show elsewhere and has no selector
+     meaning for us (single server, client tabs redirect back to operation snippets).
+     These classes are scoped to the info block — per-operation snippets are unaffected. */
+  #scalar-mount .scalar-reference-intro-server,
+  #scalar-mount .scalar-reference-intro-clients,
+  #scalar-mount .scalar-reference-intro-auth {
+    display: none;
+  }
+  /* Theme is keyed on html.dark (next-themes) NOT Scalar's own .dark-mode/.light-mode.
+     Scalar puts those on document.body (via useColorMode) and does not flip them when
+     forceDarkModeState changes — so they're locked after init. html.dark is the only
+     signal that reliably tracks Neon's toggle.
+
+     Sidebar vars are declared with literal values because Scalar's default preset sets
+     e.g. --scalar-sidebar-background-1 to var(--scalar-background-1) at body.light-mode.
+     That var() resolves at body to Scalar's default color, the resolved value inherits
+     into the sidebar, and our #scalar-mount override never reaches it. */
+  html.dark #scalar-mount,
+  html.dark #scalar-mount .dark-mode,
+  html.dark #scalar-mount .light-mode {
     --scalar-background-1: #0d0e12;
     --scalar-background-2: #131415;
     --scalar-background-3: #18191b;
@@ -73,8 +118,25 @@ const NEON_CSS = `
     --scalar-border-color: #242628;
     --scalar-font: 'IBM Plex Sans', sans-serif;
     --scalar-font-code: 'IBM Plex Mono', 'Fira Code', monospace;
+
+    --scalar-sidebar-background-1: #0d0e12;
+    --scalar-sidebar-color-1: #e4e5e7;
+    --scalar-sidebar-color-2: #afb1b6;
+    --scalar-sidebar-border-color: #242628;
+    --scalar-sidebar-item-hover-background: #131415;
+    --scalar-sidebar-item-hover-color: #afb1b6;
+    --scalar-sidebar-item-active-background: #131415;
+    --scalar-sidebar-color-active: #e4e5e7;
+    --scalar-sidebar-indent-border: #242628;
+    --scalar-sidebar-indent-border-hover: #242628;
+    --scalar-sidebar-indent-border-active: #242628;
+    --scalar-sidebar-search-background: #131415;
+    --scalar-sidebar-search-color: #797d86;
+    --scalar-sidebar-search-border-color: #242628;
   }
-  #scalar-mount .light-mode {
+  html:not(.dark) #scalar-mount,
+  html:not(.dark) #scalar-mount .dark-mode,
+  html:not(.dark) #scalar-mount .light-mode {
     --scalar-background-1: #ffffff;
     --scalar-background-2: #f2f2f3;
     --scalar-background-3: #efeff0;
@@ -86,43 +148,80 @@ const NEON_CSS = `
     --scalar-border-color: #e4e5e7;
     --scalar-font: 'IBM Plex Sans', sans-serif;
     --scalar-font-code: 'IBM Plex Mono', 'Fira Code', monospace;
+
+    --scalar-sidebar-background-1: #ffffff;
+    --scalar-sidebar-color-1: #0c0d0d;
+    --scalar-sidebar-color-2: #494b50;
+    --scalar-sidebar-border-color: #e4e5e7;
+    --scalar-sidebar-item-hover-background: #f2f2f3;
+    --scalar-sidebar-item-hover-color: #494b50;
+    --scalar-sidebar-item-active-background: #f2f2f3;
+    --scalar-sidebar-color-active: #0c0d0d;
+    --scalar-sidebar-indent-border: #e4e5e7;
+    --scalar-sidebar-indent-border-hover: #e4e5e7;
+    --scalar-sidebar-indent-border-active: #e4e5e7;
+    --scalar-sidebar-search-background: #f2f2f3;
+    --scalar-sidebar-search-color: #797d86;
+    --scalar-sidebar-search-border-color: #e4e5e7;
   }
 `;
 
-export default function ScalarMount({ spec }: { spec: string }) {
-  const { resolvedTheme } = useTheme();
+export default function ScalarMount({ spec, specUrl }: { spec: string; specUrl: string }) {
   const mountRef = useRef<HTMLDivElement>(null);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const scalarInstanceRef = useRef<any>(null);
+  const observerRef = useRef<MutationObserver | null>(null);
 
   useEffect(() => {
     const mount = mountRef.current;
     if (!mount) return;
 
-    // Treat undefined (SSR/pre-hydration) as dark to match neon's default
-    const darkMode = resolvedTheme !== 'light';
+    let cancelled = false;
 
     loadScalarCdn()
       .then(() => {
-        if (!mount) return;
-        // Clear previous Scalar instance before re-initializing
+        if (cancelled || !mount) return;
+
+        const darkMode = document.documentElement.classList.contains('dark');
+
+        // Clear placeholder so Scalar uses createApp, not createSSRApp. Scalar checks
+        // mountElement.children.length > 0 to decide — leaving our <p>Loading…</p>
+        // triggers Vue hydration and a mismatch warning.
         while (mount.firstChild) mount.removeChild(mount.firstChild);
+
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (window as any).Scalar.createApiReference('#scalar-mount', buildConfig(spec, darkMode));
+        scalarInstanceRef.current = (window as any).Scalar.createApiReference(
+          mount,
+          buildConfig(spec, specUrl, darkMode),
+        );
+
+        // Watch html.class directly — this is what next-themes mutates, and firing on
+        // it avoids the one-cycle lag of useTheme()/resolvedTheme.
+        observerRef.current = new MutationObserver(() => {
+          if (!scalarInstanceRef.current) return;
+          const isDark = document.documentElement.classList.contains('dark');
+          scalarInstanceRef.current.updateConfiguration(buildConfig(spec, specUrl, isDark));
+        });
+        observerRef.current.observe(document.documentElement, { attributeFilter: ['class'] });
       })
       .catch((err) => {
-        console.error('Scalar failed to initialize:', err);
+        if (!cancelled) console.error('[ScalarMount] init failed:', err);
       });
-  }, [spec, resolvedTheme]);
+
+    return () => {
+      cancelled = true;
+      observerRef.current?.disconnect();
+      observerRef.current = null;
+      scalarInstanceRef.current?.destroy?.();
+      scalarInstanceRef.current = null;
+    };
+  }, [spec, specUrl]);
 
   return (
     <>
       {/* eslint-disable-next-line react/no-danger */}
       <style dangerouslySetInnerHTML={{ __html: NEON_CSS }} />
-      <div
-        ref={mountRef}
-        id="scalar-mount"
-        className="w-full"
-        aria-label="API Reference"
-      >
+      <div ref={mountRef} id="scalar-mount" className="w-full" aria-label="API Reference">
         <p className="p-8 text-gray-new-50">Loading API reference…</p>
       </div>
     </>

src/app/(api-docs)/docs/api-reference-preview/page.tsx

@@ -1,7 +1,50 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+
 import ScalarMount from './ScalarMount';
 
 const SPEC_URL = 'https://neon.com/api_spec/release/v2.json';
 
+// ---------------------------------------------------------------------------
+// Content injection config
+// ---------------------------------------------------------------------------
+// Markdown files live in src/content/api-docs/. Two extension points:
+//
+//   SIDEBAR_GUIDES — standalone guide pages. Each becomes its own entry in
+//   the sidebar under the "Guides" group (above the API reference). Order
+//   here = order in the sidebar.
+//
+//   TAG_INTROS — intro content rendered above the first operation of an
+//   existing API tag. Key must match a spec tag name exactly (no-op on miss).
+//
+// To add content: drop a .md file in src/content/api-docs/ and add an entry
+// to the appropriate list.
+// ---------------------------------------------------------------------------
+
+const SIDEBAR_GUIDES: Array<{ tagName: string; file: string }> = [
+  { tagName: 'Getting Started', file: 'getting-started.md' },
+];
+
+const TAG_INTROS: Record<string, string> = {
+  Auth: 'auth-intro.md',
+  Project: 'project-intro.md',
+  Branch: 'branch-intro.md',
+  Endpoint: 'endpoint-intro.md',
+  Operation: 'operation-intro.md',
+  Consumption: 'consumption-intro.md',
+  Snapshot: 'snapshot-intro.md',
+};
+
+// Read a guide markdown file. Returns empty string on error so a missing file
+// degrades gracefully rather than breaking the page.
+async function readGuide(filename: string): Promise<string> {
+  try {
+    return await readFile(path.join(process.cwd(), 'src/content/api-docs', filename), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
 export default async function ApiReferencePage() {
   let spec: Record<string, unknown>;
 
@@ -13,9 +56,12 @@ export default async function ApiReferencePage() {
     return <p className="p-8 text-gray-new-50">Failed to load API spec. Please try again later.</p>;
   }
 
+  // --- info-block cleanup ---
+
   if (spec.info && typeof spec.info === 'object') {
     const info = spec.info as Record<string, unknown>;
     delete info.contact;
+    delete info.license;
     if (typeof info.description === 'string') {
       info.description = info.description.replaceAll(
         'https://neon.tech/docs/',
@@ -24,5 +70,69 @@ export default async function ApiReferencePage() {
     }
   }
 
-  return <ScalarMount spec={JSON.stringify(spec)} />;
+  // --- inject TAG_INTROS as descriptions on existing tags ---
+  // Scalar renders tag descriptions as a content block above the tag's
+  // operations, so this adds a rich intro without an extra sidebar entry.
+
+  if (Array.isArray(spec.tags)) {
+    const tags = spec.tags as Array<{ name: string; description?: string }>;
+    await Promise.all(
+      Object.entries(TAG_INTROS).map(async ([tagName, file]) => {
+        const content = await readGuide(file);
+        if (!content) return;
+        const tag = tags.find((t) => t.name === tagName);
+        if (tag) tag.description = content;
+      })
+    );
+  }
+
+  // --- inject SIDEBAR_GUIDES as synthetic tags so they appear in the sidebar ---
+  // Tags with no operations but a description are rendered as pages by Scalar
+  // (PR #7414, Nov 2025). "Introduction" is already auto-generated from
+  // info.description — don't duplicate it here.
+
+  const guideTags = (
+    await Promise.all(
+      SIDEBAR_GUIDES.map(async ({ tagName, file }) => {
+        const content = await readGuide(file);
+        return content ? { name: tagName, description: content } : null;
+      })
+    )
+  ).filter((t): t is { name: string; description: string } => t !== null);
+
+  if (guideTags.length > 0) {
+    const existingTags = Array.isArray(spec.tags) ? (spec.tags as Array<{ name: string }>) : [];
+    spec.tags = [...guideTags, ...existingTags];
+
+    // Collect tags actually used by at least one operation so we can drop
+    // empty-but-declared tags from the sidebar (e.g. "Preview" is defined in
+    // the spec but currently has no operations, rendering as a blank page).
+    const usedTagNames = new Set<string>();
+    if (spec.paths && typeof spec.paths === 'object') {
+      for (const pathItem of Object.values(spec.paths as Record<string, unknown>)) {
+        if (!pathItem || typeof pathItem !== 'object') continue;
+        for (const op of Object.values(pathItem as Record<string, unknown>)) {
+          if (!op || typeof op !== 'object') continue;
+          const opTags = (op as { tags?: unknown }).tags;
+          if (!Array.isArray(opTags)) continue;
+          for (const t of opTags) {
+            if (typeof t === 'string') usedTagNames.add(t);
+          }
+        }
+      }
+    }
+
+    // x-tagGroups must list every tag explicitly — anything not listed is
+    // hidden by Scalar. The "Guides" group pins our pages above the
+    // alphabetically-sorted API tags.
+    spec['x-tagGroups'] = [
+      { name: 'Guides', tags: guideTags.map((t) => t.name) },
+      {
+        name: 'API Reference',
+        tags: existingTags.map((t) => t.name).filter((n) => usedTagNames.has(n)),
+      },
+    ];
+  }
+
+  return <ScalarMount spec={JSON.stringify(spec)} specUrl={SPEC_URL} />;
 }

src/content/api-docs/auth-intro.md

@@ -0,0 +1,16 @@
+Neon Auth lets you add user authentication to your application backed by your Neon Postgres database. The endpoints below let you manage Neon Auth projects programmatically — provisioning auth for a Neon project, rotating keys, and inspecting state.
+
+## When to use this API
+
+Use the Neon Auth API when you need to automate auth setup as part of your deployment pipeline or internal tooling. If you're integrating authentication into an application, you'll typically use the [@neondatabase/auth](https://neon.com/docs/neon-auth) SDK instead, which talks to the service directly.
+
+## Prerequisites
+
+- A Neon project with the Auth feature enabled on your plan.
+- An API key with permission to manage the target project. See [Manage API keys](https://neon.com/docs/manage/api-keys) for how to create one.
+
+All requests require a bearer token in the `Authorization` header:
+
+```bash
+Authorization: Bearer $NEON_API_KEY
+```