npm - @writedocs/generator - Versions diffs - 0.1.0 - Mend

@writedocs/generator 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (95) hide show

package/LICENSE +15 -0
package/README.md +17 -0
package/astro.config.mjs +419 -0
package/bin/writedocs.js +73 -0
package/package.json +79 -0
package/src/assets/wd_watermark.png +0 -0
package/src/assets/wd_watermark_dark.png +0 -0
package/src/cli/build-auth.js +53 -0
package/src/cli/build.js +40 -0
package/src/cli/dev.js +12 -0
package/src/cli/generate-api-pages.js +359 -0
package/src/cli/init.js +81 -0
package/src/cli/preflight.js +40 -0
package/src/cli/run-astro.js +57 -0
package/src/cli/run-pagefind.js +66 -0
package/src/cli/write-redirects-file.js +80 -0
package/src/components/Accordion.astro +164 -0
package/src/components/AccordionGroup.astro +40 -0
package/src/components/ApiLangSelect.astro +168 -0
package/src/components/ApiPlayground.astro +281 -0
package/src/components/ApiReferencePanel.astro +1754 -0
package/src/components/ApiSchemaField.astro +54 -0
package/src/components/AppIcon.astro +32 -0
package/src/components/Badge.astro +128 -0
package/src/components/Callout.astro +168 -0
package/src/components/Card.astro +136 -0
package/src/components/CardGroup.astro +20 -0
package/src/components/CodeGroup.astro +184 -0
package/src/components/CopyPageMenu.astro +246 -0
package/src/components/Danger.astro +12 -0
package/src/components/Expandable.astro +126 -0
package/src/components/Frame.astro +102 -0
package/src/components/Hint.astro +99 -0
package/src/components/Icon.astro +70 -0
package/src/components/Image.astro +147 -0
package/src/components/Info.astro +12 -0
package/src/components/Note.astro +12 -0
package/src/components/Parameter.astro +119 -0
package/src/components/RequestExample.astro +33 -0
package/src/components/ResponseExample.astro +19 -0
package/src/components/Searchbar.astro +117 -0
package/src/components/Step.astro +10 -0
package/src/components/Steps.astro +32 -0
package/src/components/Tab.astro +9 -0
package/src/components/Tabs.astro +52 -0
package/src/components/Tip.astro +12 -0
package/src/components/Video.astro +135 -0
package/src/components/Warning.astro +12 -0
package/src/components/index.ts +48 -0
package/src/content.config.ts +223 -0
package/src/layout/BaseLayout.astro +750 -0
package/src/layout/components/AnalyticsScripts.astro +77 -0
package/src/layout/components/AskAiWidget.astro +37 -0
package/src/layout/components/Breadcrumbs.astro +97 -0
package/src/layout/components/ImageZoom.astro +19 -0
package/src/layout/components/MobileMenu.astro +200 -0
package/src/layout/components/NavTree.astro +351 -0
package/src/layout/components/SearchModal.astro +42 -0
package/src/layout/components/Sidebar.astro +122 -0
package/src/layout/components/SiteFooter.astro +85 -0
package/src/layout/components/TableOfContents.astro +117 -0
package/src/layout/components/TopBar.astro +311 -0
package/src/layout/styles/banner.css +44 -0
package/src/layout/styles/base.css +234 -0
package/src/layout/styles/dropdown.css +133 -0
package/src/layout/styles/footer.css +108 -0
package/src/layout/styles/image-zoom.css +50 -0
package/src/layout/styles/mobile-menu.css +258 -0
package/src/layout/styles/search-modal.css +122 -0
package/src/layout/styles/topbar.css +437 -0
package/src/lib/config.ts +2131 -0
package/src/lib/mdx-auto-hydrate.js +70 -0
package/src/lib/mdx-inject-builtins.js +87 -0
package/src/lib/mdx-substitute-variables.js +66 -0
package/src/lib/mdx-title-anchor-ids.js +84 -0
package/src/lib/mermaid-rehype.js +72 -0
package/src/lib/openapi-render.ts +479 -0
package/src/lib/shiki-code-block.js +102 -0
package/src/lib/shiki-copy-button.js +45 -0
package/src/lib/styles-asset-integration.js +210 -0
package/src/lib/writedocs-temp-dir.js +93 -0
package/src/pages/404.astro +62 -0
package/src/pages/[...slug].astro +1270 -0
package/src/pages/[...slug].md.ts +78 -0
package/src/pages/llms-full.txt.ts +71 -0
package/src/pages/llms.txt.ts +141 -0
package/src/scripts/banner.ts +20 -0
package/src/scripts/dropdowns.ts +61 -0
package/src/scripts/image-zoom.ts +66 -0
package/src/scripts/mobile-menu.ts +55 -0
package/src/scripts/search.ts +155 -0
package/src/scripts/sidebar-scroll.ts +65 -0
package/src/scripts/theme-toggle.ts +35 -0
package/src/scripts/topbar-offset.ts +141 -0
package/src/styles/global.css +18 -0

package/src/layout/BaseLayout.astro ADDED Viewed

@@ -0,0 +1,750 @@
+---
+// The site's root HTML shell: <head> meta/SEO tags, the writedocs.json
+// `integrations`/`scripts` passthrough, the color-theme flash-
+// prevention script, the dismissible `banner`, and the three-column
+// .wd-shell (sidebar/main/toc) that every page's own content lands in.
+// Everything else that used to live directly in this file - the topbar,
+// the mobile hamburger drawer, the search modal, the footer, and the
+// analytics/AI-chat integration scripts - is now its own component,
+// composed below. This file had grown to ~2200 lines covering all of
+// those unrelated concerns in one place before that split; each piece is
+// small enough on its own now to read start-to-finish without losing the
+// thread, and a change to (say) the mobile menu no longer means scrolling
+// past a thousand lines of unrelated topbar/search/footer code to find
+// the right spot. This file is the only .astro file that stays directly
+// in src/layout/ - every other component lives in src/layout/components/,
+// and every plain .css file (base.css, banner.css, and the rest each
+// component below imports for itself) lives in src/layout/styles/ - this
+// file is the layout's single entry point/orchestrator, everything else
+// is a piece it composes.
+import fs from 'node:fs';
+// Named `nodePath`, not the more natural `path` - this component already
+// destructures a prop called `path` (the current page's own URL path,
+// see Props below) from Astro.props, which would otherwise shadow a
+// module-level `path` import inside this component's own scope, silently
+// turning every `path.join(...)` call into a TypeError at render time
+// ("path.join is not a function") rather than a compile-time error, since
+// both are just plain identifiers to the bundler. Hit and fixed while
+// wiring up findRootAssets() below - real bug, not a hypothetical.
+import nodePath from 'node:path';
+import {
+  resolveSiteUrl,
+  resolveAbsoluteUrl,
+  findRootAssets,
+  resolveNavbarColor,
+  contrastTextColor,
+  resolveFonts,
+  googleFontsHref,
+  fontFaceRule,
+  type DocsConfig,
+  type Selector,
+  type GlobalDropdownView,
+  type SeoFields,
+} from '../lib/config';
+import '../styles/global.css';
+// rehypeKatex (astro.config.mjs) renders every $inline$/$$block$$ math
+// span into real KaTeX markup at build time - this is the one runtime
+// dependency that output needs: layout/glyph CSS for the .katex class
+// tree, self-hosted (bundled by Vite, fonts included via its own url()
+// asset resolution) rather than a KaTeX CDN link. Loaded site-wide, same
+// as global.css above - a page with no math in it pays for one small,
+// cached stylesheet and nothing else (no fonts are actually fetched
+// unless a page's rendered KaTeX markup uses their glyphs). KaTeX's own
+// output deliberately sets no explicit text color, inheriting `color`
+// from whatever wraps it - so it already follows this site's light/dark
+// theme with no extra CSS needed here.
+import 'katex/dist/katex.min.css';
+import './styles/base.css';
+import './styles/banner.css';
+// Astro's client-side router - swaps <body> content between same-origin
+// navigations via the native View Transition API instead of a hard
+// browser reload, so the topbar/sidebar/footer don't visibly flash/
+// "twitch" on every click the way a full document reload does. Every
+// interactive component's own <script> (TopBar's dropdowns, search,
+// TableOfContents, Mermaid, the copy-page menu, ...) already calls its
+// init function once directly *and* re-registers it on the
+// `astro:page-load` event (see e.g. TableOfContents.astro's own
+// `initToc(document); document.addEventListener('astro:page-load', ...)`
+// pair) - that event only ever fires when this router is active, so this
+// was already the intended architecture, just missing this one piece
+// that actually turns it on.
+import { ClientRouter } from 'astro:transitions';
+import TopBar from './components/TopBar.astro';
+import MobileMenu from './components/MobileMenu.astro';
+import SearchModal from './components/SearchModal.astro';
+import ImageZoom from './components/ImageZoom.astro';
+import SiteFooter from './components/SiteFooter.astro';
+import AnalyticsScripts from './components/AnalyticsScripts.astro';
+import AskAiWidget from './components/AskAiWidget.astro';
+interface Props {
+  config: DocsConfig;
+  title: string;
+  // Falls back to config.description when a page has none of its own -
+  // see [...slug].astro, which passes entry.data.description straight
+  // through without resolving the fallback itself.
+  description?: string;
+  // The current page's own path (e.g. "/" or "/guides/foo/"), used to
+  // build the canonical <link> and og:url/twitter:url - [...slug].astro
+  // already computes this via hrefForSlug(currentFileId) for its own
+  // prev/next links, so it's passed through rather than recomputed here.
+  path: string;
+  // Site-wide seo (writedocs.json) merged with this page's own frontmatter
+  // seo override - see mergeSeo() in lib/config.ts. [...slug].astro does
+  // the merging; this component just renders the result.
+  seo?: SeoFields;
+  // One Selector per level of the active page's navigation path (tabs,
+  // versions, languages, products, or a dropdown used as a nested level)
+  // - see resolveSections()/buildSelectors() in lib/config.ts for how
+  // this is computed from however the site's writedocs.json nests things.
+  // Passed straight through to TopBar.astro and MobileMenu.astro, which
+  // each derive their own view of it (TopBar's switcherSelectors/
+  // tabSelectors vs. MobileMenu's per-level accordion rows).
+  selectors?: Selector[];
+  // The always-visible topbar dropdown list from navigation.global.dropdowns
+  // - independent of the active selectors, shown on every page. Also
+  // passed straight through to TopBar.astro and MobileMenu.astro.
+  globalDropdowns?: GlobalDropdownView[];
+  // Per-page frontmatter `mode` (content.config.ts) - controls how much
+  // site chrome wraps this page. 'blank' drops the topbar and the whole
+  // .wd-shell (sidebar/toc columns) entirely, rendering only <slot />
+  // directly in <body> - see the template below. Every other mode
+  // (including 'custom') still gets the topbar; [...slug].astro is what
+  // decides whether to actually pass sidebar/toc slot content for
+  // 'wide'/'frame'/'custom' (BaseLayout has no sidebar/toc content of its
+  // own to conditionally omit - an unfilled named slot in Astro already
+  // renders nothing, so this component only needs to know whether to
+  // render the *column wrapper divs* at all).
+  mode?: 'default' | 'wide' | 'frame' | 'custom' | 'blank';
+}
+const {
+  config,
+  title,
+  description,
+  path,
+  seo = {},
+  selectors = [],
+  globalDropdowns = [],
+  mode = 'default',
+} = Astro.props as Props;
+const showSidebarCol = mode === 'default' || mode === 'wide';
+const showTocCol = mode === 'default';
+// Meta tag resolution - all derived once here rather than inline in the
+// template below, so the JSX stays a straight list of conditional <meta>
+// tags instead of repeating this logic at each call site.
+const siteUrl = resolveSiteUrl(config);
+const effectiveDescription = description ?? config.description;
+const canonicalUrl = siteUrl ? `${siteUrl}${path}` : null;
+const ogType = seo.ogType ?? 'website';
+const absoluteOgImage = seo.ogImage ? resolveAbsoluteUrl(siteUrl, seo.ogImage) : undefined;
+// summary_large_image needs a real image to make sense as a card size;
+// falls back to the smaller "summary" card when no image is set, rather
+// than always defaulting to the large-image card regardless.
+const twitterCard = seo.twitterCard ?? (absoluteOgImage ? 'summary_large_image' : 'summary');
+// Light-mode values come straight from styles.colors/styles.background
+// (with defaults); dark-mode values fall back to their light counterpart
+// when the site's own dark override doesn't set them, so a site only has
+// to specify what actually changes for dark mode. Both sets are always
+// computed and handed to the CSS below (light-mode ones as sensible
+// starting defaults, but the .wd-* class hides/shows appropriately) - see
+// the `[data-theme="dark"]` override rule below, which is what actually
+// switches which set is live. Unlike every other bit of CSS this file
+// used to own directly, this specific pair of rules can't move into a
+// plain external .css file the way base.css/banner.css did - `define:vars`
+// (right below) is what lets these raw hex/URL values get interpolated
+// into custom-property assignments at all, and that directive only works
+// on a <style> tag physically inside an .astro file's own template.
+const lightPrimary = config.styles.colors.primary;
+const lightText = config.styles.colors.text ?? '#0f172a';
+const darkPrimary = config.styles.colors.dark?.primary ?? lightPrimary;
+const darkText = config.styles.colors.dark?.text ?? '#e2e8f0';
+// styles.background.colors is now the single source for any background
+// color - both the flat --wd-background surface (dropdowns/modals/kbd
+// chips/footer/topbar-fallback/etc., every other `var(--wd-background)`
+// call site) and the <body> canvas paint below. There used to be a
+// separate styles.colors.background/colors.dark.background pair driving
+// just the --wd-background half, independent of this - see config.ts's
+// own comment on why that split was removed; `lightBackground`/
+// `darkBackground` here is what used to read that other field.
+const lightBackground = config.styles.background?.colors?.light ?? '#ffffff';
+const darkBackground = config.styles.background?.colors?.dark ?? '#0b1120';
+// The topbar/mobile-menu-panel background - falls back to the page's own
+// background (above) when a site doesn't set it, so an unconfigured navbar
+// keeps blending into the page exactly as it always has; only sites that
+// explicitly set `styles.navbar.light`/`.dark` get a topbar that looks
+// different from the page behind it. resolveNavbarColor() (lib/config.ts)
+// is what splits the string-or-{background,accent} union `navbar.light`/
+// `.dark` can now be into its two parts - see its own comment.
+const navLight = resolveNavbarColor(config.styles.navbar?.light, lightBackground);
+const navDark = resolveNavbarColor(config.styles.navbar?.dark, darkBackground);
+const lightNavbarBg = navLight.background;
+const darkNavbarBg = navDark.background;
+// Whether this side of `styles.navbar` was configured at all - string or
+// object form, doesn't matter, just "is there a writedocs.json value here" -
+// not merely "does lightNavbarBg differ from the page background", since
+// a site could deliberately set navbar to the *same* color as the page
+// background and this should still count as configured. What this gates:
+// once true, the navbar's own text/icon color stops assuming it's sitting
+// on something close to the page background (--wd-text's own tuning
+// target) and switches to being computed fresh against whatever
+// `background` actually resolved to.
+const lightNavbarConfigured = config.styles.navbar?.light !== undefined;
+const darkNavbarConfigured = config.styles.navbar?.dark !== undefined;
+// --wd-navbar-foreground/-muted: the topbar's own text/icon color, plain
+// (resting) state. Never a writedocs.json value, even indirectly - always
+// contrastTextColor(lightNavbarBg) (lib/config.ts, picks black or white by
+// luminance) the moment this side of `navbar` is configured at all, or the
+// literal --wd-text/--wd-text-muted var references when it isn't, so an
+// unconfigured navbar renders pixel-identical to before this feature
+// existed. An earlier version of this let an object-form field double as
+// both "the navbar's accent color" and "the navbar's text color" - real
+// bug, caught immediately: a site picking a light accent (to stay legible
+// against a dark/saturated background, the whole point of setting it) got
+// that same light color as its *text*, which is exactly backwards. Text
+// legibility isn't a design choice worth exposing at all here - it's
+// always computed, correctly, every time. The muted variant mixes that
+// same resolved color toward transparent (not toward lightNavbarBg, which
+// would drag it back toward the background's own hue and undo the
+// contrast fix) - a plain opacity reduction, so it stays legible
+// regardless of what hue the navbar itself happens to be.
+const lightNavbarFg = lightNavbarConfigured ? contrastTextColor(lightNavbarBg) : 'var(--wd-text)';
+const darkNavbarFg = darkNavbarConfigured ? contrastTextColor(darkNavbarBg) : 'var(--wd-text)';
+const lightNavbarFgMuted = lightNavbarConfigured
+  ? `color-mix(in srgb, ${lightNavbarFg} 70%, transparent)`
+  : 'var(--wd-text-muted)';
+const darkNavbarFgMuted = darkNavbarConfigured
+  ? `color-mix(in srgb, ${darkNavbarFg} 70%, transparent)`
+  : 'var(--wd-text-muted)';
+// --wd-navbar-accent: the tab-hover-underline/active-tab-fill color inside
+// the topbar specifically - `accent` on the object form (a real, legitimate
+// design choice, unlike text color above), falling back to the sitewide
+// --wd-primary (today's exact behavior) when unset - a site that sets a
+// navbar background but no accent keeps its ordinary brand-colored
+// active-tab fill exactly as before.
+const lightNavbarAccent = navLight.accent ?? lightPrimary;
+const darkNavbarAccent = navDark.accent ?? darkPrimary;
+// --wd-navbar-accent-text: the active tab's own text color, painted on top
+// of --wd-navbar-accent above. Hardcoded to white before this feature
+// existed, which only ever looked right because every accent color in
+// practice (always --wd-primary until now) happened to be dark/saturated
+// enough for white text - contrastTextColor() (lib/config.ts) picks
+// black or white by actual luminance instead, so a light `accent` (e.g.
+// a pale one against a dark navbar) still gets legible active-tab text
+// rather than assuming white always works.
+const lightNavbarAccentText = contrastTextColor(lightNavbarAccent);
+const darkNavbarAccentText = contrastTextColor(darkNavbarAccent);
+// --wd-navbar-border: the switcher pills' (version/language/product) own
+// border. Never the flat --wd-border (a fixed neutral gray/slate tuned for
+// sitting on the page background) once navbar is configured - that reads
+// as a harsh, near-white outline against a saturated/colored navbar
+// background, since it's not picked with that background in mind at all.
+// Same mix-toward-transparent technique as the muted foreground above: a
+// low-opacity tint of the already-contrast-correct navbarFg, so it stays
+// soft and legible against any navbar hue instead of a flat, unrelated
+// gray. Unconfigured navbar keeps the literal var(--wd-border) reference,
+// pixel-identical to before this existed.
+const lightNavbarBorder = lightNavbarConfigured
+  ? `color-mix(in srgb, ${lightNavbarFg} 25%, transparent)`
+  : 'var(--wd-border)';
+const darkNavbarBorder = darkNavbarConfigured
+  ? `color-mix(in srgb, ${darkNavbarFg} 25%, transparent)`
+  : 'var(--wd-border)';
+// The <body> canvas's own paint - same color as --wd-background above
+// (there's only one background color to configure now), plus an optional
+// image layered on top. `images.light`/`.dark` are plain public/-relative
+// paths (same convention as styles.logo/favicon) - wrapped in url(...) here
+// (or 'none' when unset) since CSS custom properties can't have url()
+// applied to them after the fact (`url(var(--x))` isn't valid CSS - the
+// value itself has to already be a full `url(...)` token, which is what
+// these two variables hold).
+const lightPageBgColor = lightBackground;
+const darkPageBgColor = darkBackground;
+const lightPageBgImage = config.styles.background?.images?.light
+  ? `url('${config.styles.background.images.light}')`
+  : 'none';
+const darkPageBgImage = config.styles.background?.images?.dark
+  ? `url('${config.styles.background.images.dark}')`
+  : 'none';
+// A logo is either one path used for both modes, or a {light, dark,
+// label} object - normalized to a single light/dark pair here (the one
+// place that needs to know which form writedocs.json used) so TopBar.astro,
+// MobileMenu.astro, and SiteFooter.astro - each of which render their own
+// copy of the brand link - never need to branch on it themselves. The
+// brand link shows the image(s) alone by default - no site name text next
+// to it, since a real logo asset is usually already a wordmark. `label`
+// (only settable on the object form - see config.ts) opts back into
+// showing text next to the image - or, since `light`/`dark` are
+// themselves optional on that form, stands entirely on its own:
+// `styles.logo: { label: "..." }` with no images at all overrides just the
+// brand text without adding any logo image. A site with neither a logo
+// image nor a label falls back to plain config.name text, so the brand
+// link is never left empty.
+const logo = config.styles.logo;
+const logoLight = typeof logo === 'string' ? logo : logo?.light;
+const logoDark = typeof logo === 'string' ? logo : logo?.dark;
+const logoLabel = typeof logo === 'string' ? undefined : logo?.label;
+const hasLogoImage = Boolean(logoLight || logoDark);
+const brandLabel = logoLabel ?? (hasLogoImage ? undefined : config.name);
+// writedocs.json's `footer.logo` (same {light, dark, label} shape as
+// `styles.logo` above, via config.ts's shared logoSchema) - unset by
+// default, in which case SiteFooter.astro just gets the same
+// logoLight/logoDark/logoLabel as the topbar/mobile menu above. Set, it
+// replaces those entirely (not just fills in whichever side is missing)
+// before ever reaching SiteFooter - a footer wanting a different mark
+// than the topbar (or none at all - `styles.logo` set, `footer.logo`
+// deliberately absent-of-images-but-present, e.g. `{ label: "" }`, isn't
+// a real use case worth solving here) shouldn't still show the sitewide
+// one alongside or underneath it.
+const footerLogoConfig = config.footer.logo;
+const footerLogoLight = footerLogoConfig
+  ? typeof footerLogoConfig === 'string'
+    ? footerLogoConfig
+    : footerLogoConfig.light
+  : logoLight;
+const footerLogoDark = footerLogoConfig
+  ? typeof footerLogoConfig === 'string'
+    ? footerLogoConfig
+    : footerLogoConfig.dark
+  : logoDark;
+// Zero-config custom CSS/JS - any `.css`/`.js` file anywhere in the
+// project (root, `docs/`, `snippets/`, `public/`, any subfolder -
+// `dist/`/`node_modules/`/etc. excluded, see findRootAssets() in
+// lib/config.ts) is auto-loaded on every page, no writedocs.json entry
+// needed. Read fresh on every render (not cached at module scope) so an
+// edit to one of these files shows up on the next `writedocs dev` page
+// load without a server restart - same freshness `loadDocsConfig(contentDir)`
+// itself already gives writedocs.json edits in [...slug].astro/404.astro.
+// Rendered in addition to, not instead of, writedocs.json's own explicit
+// `scripts` field - that still exists for external/CDN script URLs
+// (`src`) and inline content that should only load under deliberate
+// config, and renders before these so a file living in the project (the
+// more locally-owned override) wins over a URL possibly pointing at
+// someone else's asset.
+const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+const rootAssets = findRootAssets(contentDir);
+// `name` is a POSIX-separated path relative to contentDir (e.g.
+// "docs/theme.css") - split and rejoin with nodePath.join rather than
+// handing the raw string straight to it, so a nested asset resolves
+// correctly on every OS this might run on, not just POSIX ones.
+const rootCssContents = rootAssets.css.map((name) => fs.readFileSync(nodePath.join(contentDir, ...name.split('/')), 'utf-8'));
+const rootJsContents = rootAssets.js.map((name) => fs.readFileSync(nodePath.join(contentDir, ...name.split('/')), 'utf-8'));
+// public/*.css and public/*.js auto-load too, but as <link>/<script src>
+// pointing at their already-public URL (see findRootAssets()'s own
+// comment for why - no point inlining a file that's also independently
+// fetchable at that exact URL). publicJsHrefs is filtered against
+// writedocs.json's own `scripts.head` so a site that hasn't yet removed an
+// explicit `src` entry for the same public/ file doesn't get that href
+// rendered twice - the explicit entry still works, it's just redundant
+// with this now. publicCssHrefs has no equivalent filter to apply -
+// there's no explicit stylesheet-URL config field anymore.
+const explicitScriptSrcs = new Set(config.scripts.head.map((s) => s.src).filter((src): src is string => Boolean(src)));
+const publicCssHrefs = rootAssets.publicCss;
+const publicJsHrefs = rootAssets.publicJs.filter((href) => !explicitScriptSrcs.has(href));
+// styles.fonts (see fontsSchema/resolveFonts() in lib/config.ts) - resolves
+// to plain Inter, genuinely loaded via Google Fonts (not just named in a
+// fallback stack the way base.css used to), when a site sets no `fonts`
+// field at all. `fontStack()` quotes the family name (safe even for a
+// single-word name, and required for one with spaces like "Playfair
+// Display") and appends the same system-font fallback chain base.css
+// always used, so a reader who somehow loads the page before the web font
+// finishes fetching still sees a reasonable font rather than the browser
+// default serif. `heading`/`body` are left `null` (not defaulted to the
+// same value as `base`) whenever a site hasn't overridden them - base.css
+// falls back to `--wd-font-family` itself via CSS var(), so a `null` here
+// deliberately never gets its own CSS var written into the style block
+// below.
+const resolvedFonts = resolveFonts(config);
+const fontsGoogleHref = googleFontsHref(resolvedFonts);
+function fontStack(family: string): string {
+  return `'${family}', -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`;
+}
+// heading/body already fall back to `resolvedFonts.base` right here (not
+// left as a CSS var() fallback chain for :root below to resolve) - same
+// "fully resolve in JS, plain values into define:vars" approach every
+// other themeable value in this file already uses (see lightPrimary/
+// darkPrimary etc. above), rather than introducing a different pattern
+// just for fonts.
+const wdFontFamily = fontStack(resolvedFonts.base.family);
+const wdFontFamilyHeading = resolvedFonts.heading ? fontStack(resolvedFonts.heading.family) : wdFontFamily;
+const wdFontFamilyBody = resolvedFonts.body ? fontStack(resolvedFonts.body.family) : wdFontFamily;
+// One @font-face rule per source-based font actually configured (Google
+// Fonts, covered by fontsGoogleHref above instead, never reach here) - this
+// only ever gets the right *file* loaded (the @font-face `font-weight`
+// descriptor, or the Google Fonts URL's `:wght@` axis inside
+// googleFontsHref() above), not the actual rendered boldness of any
+// element - see wdFontWeightCss right below for that other half.
+const fontFaceCss = [fontFaceRule(resolvedFonts.base), fontFaceRule(resolvedFonts.heading), fontFaceRule(resolvedFonts.body)]
+  .filter(Boolean)
+  .join('\n');
+// Without this, a configured `weight` only ever changed which font *file*
+// loaded - h1-h6 still rendered at the browser's own default `font-weight:
+// bold` (a user-agent-stylesheet rule, present regardless of which file
+// actually loaded), so a heading weight of e.g. 400 was silently faux-
+// bolded back to looking bold anyway, with no visible effect from
+// changing the config at all. `resolvedFonts.heading?.weight ?? base.weight`
+// falls back the same way family already does (an override with no
+// weight of its own still inherits the top-level one); `undefined` when
+// nothing at any level configured a weight, which deliberately renders no
+// rule at all here - an unconfigured site keeps today's plain browser-
+// default bold headings/normal body text exactly as before this feature
+// existed, not a forced 400/700 nobody asked for.
+const wdFontWeightHeading = resolvedFonts.heading?.weight ?? resolvedFonts.base.weight;
+const wdFontWeightBody = resolvedFonts.body?.weight ?? resolvedFonts.base.weight;
+const fontWeightCss = [
+  wdFontWeightHeading !== undefined ? `h1, h2, h3, h4, h5, h6 { font-weight: ${wdFontWeightHeading}; }` : '',
+  wdFontWeightBody !== undefined ? `body { font-weight: ${wdFontWeightBody}; }` : '',
+]
+  .filter(Boolean)
+  .join('\n');
+const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title} · {config.name}</title>
+    <ClientRouter />
+    {effectiveDescription && <meta name="description" content={effectiveDescription} />}
+    {seo.keywords && seo.keywords.length > 0 && <meta name="keywords" content={seo.keywords.join(', ')} />}
+    {seo.noindex && <meta name="robots" content="noindex, nofollow" />}
+    {canonicalUrl && <link rel="canonical" href={canonicalUrl} />}
+    {config.styles.favicon && <link rel="icon" href={config.styles.favicon} />}
+    {/* styles.fonts - see resolveFonts()/googleFontsHref() in lib/config.ts.
+        Present (non-null) whenever at least one configured font (or the
+        Inter default, when styles.fonts is unset entirely) has no `source`
+        - i.e. is a Google Font, auto-loaded by family name. The two
+        preconnect hints warm up the connections googleapis.com's own CSS
+        response will immediately need (its @font-face rules point at
+        gstatic.com for the actual font files) before the browser has even
+        parsed that response - Google's own recommended pattern for using
+        their fonts. Rendered this early in <head> (right after favicon,
+        before Open Graph/Twitter meta) so the font starts loading as soon
+        as possible rather than competing with less render-critical tags
+        for bandwidth/priority. */}
+    {fontsGoogleHref && (
+      <>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+        <link rel="stylesheet" href={fontsGoogleHref} />
+      </>
+    )}
+    <!-- Open Graph -->
+    <meta property="og:title" content={title} />
+    {effectiveDescription && <meta property="og:description" content={effectiveDescription} />}
+    <meta property="og:type" content={ogType} />
+    <meta property="og:site_name" content={config.name} />
+    {canonicalUrl && <meta property="og:url" content={canonicalUrl} />}
+    {absoluteOgImage && <meta property="og:image" content={absoluteOgImage} />}
+    <!-- Twitter card -->
+    <meta name="twitter:card" content={twitterCard} />
+    <meta name="twitter:title" content={title} />
+    {effectiveDescription && <meta name="twitter:description" content={effectiveDescription} />}
+    {absoluteOgImage && <meta name="twitter:image" content={absoluteOgImage} />}
+    {/* writedocs.json's `integrations` (the six analytics providers) - see
+        AnalyticsScripts.astro. Rendered as early in <head> as reasonably
+        possible (right after the meta tags, before even the theme-
+        detection script below) - the usual placement every one of these
+        providers' own install instructions ask for, so pageview timing is
+        captured as close to actual page load as it can be. */}
+    <AnalyticsScripts config={config} />
+    <script is:inline>
+      // Sets [data-theme] and [data-banner-dismissed] on <html> before
+      // first paint, so the page never flashes the wrong mode or an
+      // already-dismissed banner. Preference order for theme: an explicit
+      // prior choice (localStorage), then the OS-level preference,
+      // defaulting to light. The click handlers that update both live in
+      // src/scripts/theme-toggle.ts and src/scripts/banner.ts.
+      //
+      // Also re-run on `astro:after-swap` (ClientRouter, see BaseLayout's
+      // own import of it below), not just the initial load - Astro's
+      // client-side navigation swaps <html>'s attributes wholesale to
+      // match the newly-fetched page's raw server-rendered markup (see
+      // swapRootAttributes() in astro/dist/transitions/swap-functions.js),
+      // which has neither of these dataset attributes baked in since
+      // they're pure client-side runtime state, not something the server
+      // ever renders. Without re-running this after every swap, a
+      // dismissed banner (or a chosen dark theme) would silently come
+      // back on the very next navigation - both attributes get wiped, not
+      // just reset to their default, so this has to unconditionally
+      // reapply them from localStorage every time, exactly as it does on
+      // first load. `astro:after-swap` fires synchronously right after
+      // that swap and before the browser's next paint, so this still
+      // prevents any visible flash on client-side navigations too.
+      function wdApplyStoredPreferences() {
+        try {
+          var stored = localStorage.getItem('wd-theme');
+          var theme = stored === 'light' || stored === 'dark'
+            ? stored
+            : (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+          document.documentElement.dataset.theme = theme;
+        } catch (e) {
+          document.documentElement.dataset.theme = 'light';
+        }
+        try {
+          document.documentElement.dataset.bannerDismissed = localStorage.getItem('wd-banner-dismissed') === 'true' ? 'true' : 'false';
+        } catch (e) {
+          document.documentElement.dataset.bannerDismissed = 'false';
+        }
+      }
+      wdApplyStoredPreferences();
+      document.addEventListener('astro:after-swap', wdApplyStoredPreferences);
+    </script>
+    <script>
+      // Preserves the sidebar's own scroll position across a ClientRouter
+      // navigation - see src/scripts/sidebar-scroll.ts for why this is
+      // needed at all (the sidebar is re-rendered fresh, server-side, on
+      // every page, so it's a brand-new DOM node each time, reset to
+      // scrollTop 0 like a real page reload would be). Same before-swap/
+      // after-swap pairing as wdApplyStoredPreferences above, and for the
+      // same reason: after-swap fires before the next paint, so there's no
+      // visible flash of the sidebar sitting at the top before jumping
+      // back to where the reader had it scrolled.
+      import { saveSidebarScroll, restoreSidebarScroll } from '../scripts/sidebar-scroll';
+      document.addEventListener('astro:before-swap', saveSidebarScroll);
+      document.addEventListener('astro:after-swap', restoreSidebarScroll);
+    </script>
+    <style
+      define:vars={{
+        wdPrimaryLight: lightPrimary,
+        wdBackgroundLight: lightBackground,
+        wdTextLight: lightText,
+        wdNavbarLight: lightNavbarBg,
+        wdNavbarFgLight: lightNavbarFg,
+        wdNavbarFgMutedLight: lightNavbarFgMuted,
+        wdNavbarAccentLight: lightNavbarAccent,
+        wdNavbarAccentTextLight: lightNavbarAccentText,
+        wdNavbarBorderLight: lightNavbarBorder,
+        wdPageBgColorLight: lightPageBgColor,
+        wdPageBgImageLight: lightPageBgImage,
+        wdFontFamily,
+        wdFontFamilyHeading,
+        wdFontFamilyBody,
+        wdPrimaryDark: darkPrimary,
+        wdBackgroundDark: darkBackground,
+        wdTextDark: darkText,
+        wdNavbarDark: darkNavbarBg,
+        wdNavbarFgDark: darkNavbarFg,
+        wdNavbarFgMutedDark: darkNavbarFgMuted,
+        wdNavbarAccentDark: darkNavbarAccent,
+        wdNavbarAccentTextDark: darkNavbarAccentText,
+        wdNavbarBorderDark: darkNavbarBorder,
+        wdPageBgColorDark: darkPageBgColor,
+        wdPageBgImageDark: darkPageBgImage,
+      }}
+    >
+      :root {
+        --wd-primary: var(--wdPrimaryLight);
+        --wd-background: var(--wdBackgroundLight);
+        --wd-text: var(--wdTextLight);
+        --wd-navbar-background: var(--wdNavbarLight);
+        --wd-navbar-foreground: var(--wdNavbarFgLight);
+        --wd-navbar-foreground-muted: var(--wdNavbarFgMutedLight);
+        --wd-navbar-accent: var(--wdNavbarAccentLight);
+        --wd-navbar-accent-text: var(--wdNavbarAccentTextLight);
+        --wd-navbar-border: var(--wdNavbarBorderLight);
+        --wd-page-bg-color: var(--wdPageBgColorLight);
+        --wd-page-bg-image: var(--wdPageBgImageLight);
+        --wd-text-muted: #64748b;
+        --wd-border: #e2e8f0;
+        --wd-surface: #f8fafc;
+        /* 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. */
+        --wd-font-family: var(--wdFontFamily);
+        --wd-font-family-heading: var(--wdFontFamilyHeading);
+        --wd-font-family-body: var(--wdFontFamilyBody);
+      }
+      /* Higher specificity than the plain :root rule above (an attribute
+         selector on :root beats an unqualified one), so this wins
+         regardless of source order once data-theme is set to "dark" by
+         the inline script above or the toggle button's click handler
+         (src/scripts/theme-toggle.ts). */
+      :root[data-theme='dark'] {
+        --wd-primary: var(--wdPrimaryDark);
+        --wd-background: var(--wdBackgroundDark);
+        --wd-text: var(--wdTextDark);
+        --wd-navbar-background: var(--wdNavbarDark);
+        --wd-navbar-foreground: var(--wdNavbarFgDark);
+        --wd-navbar-foreground-muted: var(--wdNavbarFgMutedDark);
+        --wd-navbar-accent: var(--wdNavbarAccentDark);
+        --wd-navbar-accent-text: var(--wdNavbarAccentTextDark);
+        --wd-navbar-border: var(--wdNavbarBorderDark);
+        --wd-page-bg-color: var(--wdPageBgColorDark);
+        --wd-page-bg-image: var(--wdPageBgImageDark);
+        --wd-text-muted: #94a3b8;
+        --wd-border: #1e293b;
+        --wd-surface: #131a2b;
+      }
+    </style>
+    {/* styles.fonts: local/externally-hosted font(s) (fontFaceRule() in
+        lib/config.ts - a local `source` path resolves the same way
+        styles.favicon/styles.logo/styles.background.images already do, see
+        collectConfiguredAssetPaths() + styles-asset-integration.js, no
+        extra wiring needed here beyond listing it there), plus a
+        font-weight override for h1-h6/body whenever `weight` was actually
+        configured somewhere (fontWeightCss above) - both concatenated
+        into one block since both need the same raw-CSS-text treatment.
+        set:html (not a plain <style>{fontExtraCss}</style>) because this
+        needs to render already-built CSS text as-is, not have Astro's own
+        CSS parser/scoper attempt to process an `@font-face` block or a
+        bare `h1, h2, ...` selector list assembled as a runtime string -
+        empty string renders nothing when neither piece has anything to
+        contribute (every configured font is a Google Font, and no
+        `weight` was set anywhere in `styles.fonts`). */}
+    {fontExtraCss && <style set:html={fontExtraCss} />}
+    {/* writedocs.json's `scripts.head` - see scriptEntrySchema in lib/config.ts.
+        Each entry is exactly one of an external/local `src` or inline
+        `content` (enforced by the schema's own .refine()), rendered right
+        before </head> so it runs before body content paints - the usual
+        spot a third-party script's own install instructions ask for. */}
+    {config.scripts.head.map((s) =>
+      s.src ? <script is:inline src={s.src} /> : <script is:inline set:html={s.content} />
+    )}
+    {/* Zero-config custom CSS - see findRootAssets() in lib/config.ts and
+        rootCssContents above. Rendered last in <head>, so a project-owned
+        file - anywhere in the project, not just the root - wins over
+        everything else writedocs generates itself. Inlined as raw <style>
+        content rather than a <link> - these files aren't necessarily under
+        `public/`, so there's no guaranteed build-time copy step making them
+        independently fetchable as a URL; inlining sidesteps needing one.
+        One <style> tag per file (not concatenated) so each is independently
+        visible/attributable
+        in devtools. */}
+    {rootCssContents.map((content) => (
+      <style is:inline set:html={content} />
+    ))}
+    {/* Zero-config custom CSS living in public/ - see findRootAssets()'s
+        own comment in lib/config.ts for why these render as <link> tags
+        pointing at their already-public URL instead of joining
+        rootCssContents above as inlined content. */}
+    {publicCssHrefs.map((href) => (
+      <link rel="stylesheet" href={href} />
+    ))}
+  </head>
+  <body>
+    {mode === 'blank' ? (
+      // No site chrome at all - no topbar, no sidebar/toc columns, not
+      // even the .wd-shell wrapper's own max-width - the page's own
+      // MDX/components control 100% of the layout, including whether
+      // there's any nav/branding at all. SearchModal.astro's own overlay
+      // markup and its ⌘K listener still work even with no visible
+      // trigger button to click (it's rendered unconditionally below,
+      // outside this mode === 'blank' branch), so that's left in rather
+      // than also gated on mode.
+      <slot />
+    ) : (
+      <Fragment>
+    {/* Everything above the footer, in one wrapper - see .wd-page/body in
+        base.css: body is a flex column, this is its flex: 1 0 auto item,
+        and the footer (a plain sibling below, not inside this wrapper) is
+        what that pushes down to the viewport's bottom edge on a page
+        short enough not to need scrolling - the "sticky footer" pattern,
+        not position: sticky/fixed (either of which would cover page
+        content instead of just trailing it once actually reached). */}
+    <div class="wd-page">
+    {config.banner && (
+      <div class={`wd-banner wd-banner-${config.banner.type}`} id="wd-banner">
+        <div class="wd-banner-inner">
+          <span class="wd-banner-content">{config.banner.content}</span>
+          {config.banner.dismissible && (
+            <button type="button" class="wd-banner-dismiss" aria-label="Dismiss banner" data-banner-dismiss>
+              &times;
+            </button>
+          )}
+        </div>
+      </div>
+    )}
+    <TopBar
+      config={config}
+      selectors={selectors}
+      globalDropdowns={globalDropdowns}
+      showSidebarCol={showSidebarCol}
+      logoLight={logoLight}
+      logoDark={logoDark}
+      brandLabel={brandLabel}
+    />
+    <MobileMenu
+      config={config}
+      selectors={selectors}
+      globalDropdowns={globalDropdowns}
+      showSidebarCol={showSidebarCol}
+      logoLight={logoLight}
+      logoDark={logoDark}
+      brandLabel={brandLabel}
+    >
+      <slot name="sidebar" slot="sidebar" />
+    </MobileMenu>
+    <div class="wd-shell">
+      {showSidebarCol && <div class="wd-sidebar-col"><slot name="sidebar" /></div>}
+      <div class="wd-main-col"><slot /></div>
+      {showTocCol && <div class="wd-toc-col"><slot name="toc" /></div>}
+    </div>
+    </div>
+    <SiteFooter config={config} logoLight={footerLogoLight} logoDark={footerLogoDark} />
+      </Fragment>
+    )}
+    <SearchModal />
+    <ImageZoom />
+    <script>
+      import { initBanner } from '../scripts/banner';
+      import { initTopbarOffset } from '../scripts/topbar-offset';
+      initBanner(document);
+      document.addEventListener('astro:page-load', () => initBanner(document));
+      // No ordering dependency on initBanner above - see topbar-offset.ts
+      // for why it measures only the topbar itself (not the banner) and
+      // why that's live-measured rather than a fixed CSS value.
+      initTopbarOffset();
+      document.addEventListener('astro:page-load', () => initTopbarOffset());
+    </script>
+    {/* writedocs.json's `scripts.body` - see scriptEntrySchema in lib/config.ts.
+        Rendered after everything above (including every component's own
+        <script> tags, which Astro/Vite already bundles to run in document
+        order) so it runs after every other script on the page has already
+        loaded/hydrated - matching where a third-party script's own install
+        instructions usually ask for a "body end" placement. */}
+    {config.scripts.body.map((s) =>
+      s.src ? <script is:inline src={s.src} /> : <script is:inline set:html={s.content} />
+    )}
+    {/* Zero-config custom JS - see findRootAssets() in lib/config.ts and
+        rootJsContents above. Rendered last, after writedocs.json's own
+        `scripts.body`, same "most locally-owned override runs last"
+        reasoning as the root CSS above. `is:inline` here isn't optional -
+        without it, Astro tries to process/bundle the tag as a module and
+        the build fails outright ("Cannot find the built path for ...
+        type=script&index=N") the same way a dynamic-`src` script did
+        while this file's own writedocs.json `scripts` support was first being
+        built - see that feature's own commit for the full story. */}
+    {rootJsContents.map((content) => (
+      <script is:inline set:html={content} />
+    ))}
+    {/* Zero-config custom JS living in public/ - see this file's own CSS
+        equivalent above and findRootAssets()'s comment in lib/config.ts.
+        `<script src>`, not `is:inline set:html` - the file's already a
+        fetchable URL, no reason to inline its content. Filtered against
+        config.scripts.head's own `src` entries (publicJsHrefs) for the
+        same duplicate-tag reason as the CSS <link>s above - note this
+        only dedupes against `scripts.head`, not `scripts.body` (a public/
+        file explicitly listed there instead would still also render here
+        as a second tag; `scripts.head` vs `scripts.body` placement is a
+        deliberate choice this can't second-guess, but `head` is by far
+        the more common spot for a plain local script and this hasn't come
+        up in practice). */}
+    {publicJsHrefs.map((href) => (
+      <script is:inline src={href} />
+    ))}
+    {/* writedocs.json's `integrations.askAi` - see AskAiWidget.astro. Rendered
+        last of all - it's a floating chat widget, not something anything
+        else on the page depends on running before, so there's no reason
+        to load it any earlier than absolutely last. */}
+    <AskAiWidget config={config} />
+  </body>
+</html>