@writedocs/generator 0.1.0

package/src/layout/components/NavTree.astro

@@ -0,0 +1,351 @@
+---
+import { navTreeContainsSlug, isExternalHref, type NavTreeNode } from "../../lib/config";
+import { methodClass } from "../../lib/openapi-render";
+
+interface Props {
+  nodes: NavTreeNode[];
+  hrefForSlug: (slug: string) => string;
+  currentSlug: string;
+  depth?: number;
+}
+
+const { nodes, hrefForSlug, currentSlug, depth = 0 } = Astro.props as Props;
+---
+
+<ul class={`wd-nav-list wd-nav-depth-${depth}`}>
+  {
+    nodes.map((node) => {
+      if (node.kind === "page") {
+        return (
+          <li>
+            <a href={hrefForSlug(node.slug)} class={node.slug === currentSlug ? "active" : ""}>
+              {node.method && (
+                <span class={`wd-nav-method wd-nav-method-${methodClass(node.method)}`}>{node.method}</span>
+              )}
+              <span class="wd-nav-title">{node.title}</span>
+            </a>
+          </li>
+        );
+      }
+
+      if (node.kind === "link") {
+        // A bare external link sitting directly in the page tree (see
+        // NavItem's `{ label, href }` leaf in lib/config.ts) - styled like
+        // a page row, but never "active" (it's not a content page) and
+        // always opens in a new tab since it's meant to point off-site.
+        const external = isExternalHref(node.href);
+        return (
+          <li>
+            <a
+              href={node.href}
+              class="wd-nav-link-leaf"
+              target={external ? "_blank" : undefined}
+              rel={external ? "noopener noreferrer" : undefined}
+            >
+              <span>{node.label}</span>
+              {external && (
+                <svg class="wd-nav-external-icon" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                  <path
+                    d="M3 1.5H8.5V7M8.5 1.5L1.5 8.5"
+                    stroke="currentColor"
+                    stroke-width="1.2"
+                    fill="none"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  />
+                </svg>
+              )}
+            </a>
+          </li>
+        );
+      }
+
+      if (depth === 0) {
+        // Top-level group = a static sidebar section title, never a
+        // disclosure control - matches the reference design where the first
+        // group level is just a bold label above its pages.
+        return (
+          <li class="wd-nav-group">
+            <div class="wd-nav-section-title">
+              {node.pageSlug ? (
+                <a href={hrefForSlug(node.pageSlug)} class={node.pageSlug === currentSlug ? "active" : ""}>
+                  {node.label}
+                </a>
+              ) : (
+                node.label
+              )}
+            </div>
+            <Astro.self nodes={node.children} hrefForSlug={hrefForSlug} currentSlug={currentSlug} depth={depth + 1} />
+          </li>
+        );
+      }
+
+      // Depth >= 1: a nested group renders as a collapsible row, styled and
+      // inset exactly like a sibling page link, with a chevron on the
+      // right. Defaults open whenever the active page lives anywhere inside
+      // it (itself or a descendant), so landing on a child page never
+      // leaves its own parent collapsed.
+      const isActive = node.pageSlug === currentSlug;
+      const open = isActive || navTreeContainsSlug(node.children, currentSlug);
+      return (
+        <li class="wd-nav-collapsible">
+          <details open={open}>
+            <summary class={isActive ? "active" : ""}>
+              {node.pageSlug ? (
+                <a href={hrefForSlug(node.pageSlug)} class={isActive ? "active" : ""}>
+                  {node.label}
+                </a>
+              ) : (
+                <span class="wd-nav-group-label">{node.label}</span>
+              )}
+              <svg class="wd-nav-chevron" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                <path
+                  d="M3.5 2L6.5 5L3.5 8"
+                  stroke="currentColor"
+                  stroke-width="1.4"
+                  fill="none"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                />
+              </svg>
+            </summary>
+            <Astro.self nodes={node.children} hrefForSlug={hrefForSlug} currentSlug={currentSlug} depth={depth + 1} />
+          </details>
+        </li>
+      );
+    })
+  }
+</ul>
+
+<style>
+  .wd-nav-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .wd-nav-list li a,
+  .wd-nav-list li summary {
+    border-left: 1px solid transparent;
+  }
+
+  .wd-nav-list li a:not(summary a):hover,
+  .wd-nav-list li summary:hover {
+    border-left: 1px solid var(--wd-primary);
+  }
+
+  .wd-nav-list li a.active:not(summary a),
+  .wd-nav-list li summary.active {
+    border-left: 1px solid var(--wd-primary);
+  }
+
+  .wd-nav-depth-0 {
+    margin-bottom: 1.25rem;
+  }
+  .wd-nav-section-title {
+    padding: 0;
+    margin-bottom: 0.4rem;
+    color: var(--wd-text-muted);
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+  /* Overrides `.wd-nav-list a`'s own block/padding/font-size/pill-when-
+     active styling further below - without this, a group-with-a-page's
+     title (e.g. "Concepts" linking to its own overview page) inherits
+     the same big rounded background pill a regular page row gets when
+     active, which looks completely out of place sitting next to a
+     plain-text sibling title like "Getting Started". A linked section
+     title should still read as a section title - same size/weight/
+     case/color as an unlinked one - just tinted primary on hover/active
+     instead. The extra `.wd-nav-group` ancestor qualifier (2 classes)
+     is load-bearing, not decoration: `.wd-nav-section-title a` alone
+     has the exact same specificity as `.wd-nav-list a` (1 class + 1
+     type each), so whichever rule happens to sit later in the
+     stylesheet would silently win regardless of intent - this avoids
+     that tie entirely. Mirrors the same "override to neutral, re-apply
+     only color" pattern already used for .wd-nav-collapsible summary a
+     below (which sidesteps the same tie via a `summary` type selector
+     instead). */
+  .wd-nav-group .wd-nav-section-title a {
+    display: inline;
+    padding: 0;
+    border-radius: 0;
+    background: none;
+    color: inherit;
+    font-size: inherit;
+    font-weight: inherit;
+    text-decoration: none;
+  }
+  .wd-nav-group .wd-nav-section-title a.active,
+  .wd-nav-group .wd-nav-section-title a:hover {
+    background: none;
+    color: var(--wd-primary);
+  }
+  .wd-nav-depth-1,
+  .wd-nav-depth-2,
+  .wd-nav-depth-3 {
+    margin-bottom: 0.5rem;
+    border-left: 1px solid var(--wd-border);
+  }
+
+  .wd-nav-depth-2,
+  .wd-nav-depth-3 {
+    margin-bottom: 0.5rem;
+    margin-left: 0.75rem;
+    border-left: 1px solid var(--wd-border);
+  }
+  .wd-nav-list a {
+    display: flex;
+    align-items: center;
+    gap: 0.45rem;
+    padding: 0.2rem 0.75rem;
+    margin: 0.1rem 0;
+    border-radius: 0 0.4rem 0.4rem 0;
+    text-decoration: none;
+    color: var(--wd-text-muted);
+    font-size: 0.9rem;
+  }
+  /* Primary-tinted rather than a neutral surface gray - a faint preview
+     of the active pill's own color (12% alpha), at half its strength, so
+     hover reads as "this could become active" instead of a generic
+     hover state shared with every other clickable thing on the page. */
+  .wd-nav-list a:hover {
+    background: color-mix(in srgb, var(--wd-primary) 6%, transparent);
+    color: var(--wd-text);
+  }
+  .wd-nav-list a.active {
+    background: color-mix(in srgb, var(--wd-primary) 12%, transparent);
+    color: var(--wd-primary);
+    font-weight: 500;
+  }
+  .wd-nav-title {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    /* text-overflow: ellipsis;
+    white-space: nowrap; */
+  }
+  .wd-nav-method {
+    flex-shrink: 0;
+    display: inline-block;
+    padding: 0.05rem 0.4rem;
+    border-radius: 0.3rem;
+    font-size: 0.62rem;
+    font-weight: 700;
+    letter-spacing: 0.02em;
+    line-height: 1.5;
+  }
+  .wd-nav-method-get {
+    background: color-mix(in srgb, #16a34a 15%, transparent);
+    color: #16a34a;
+  }
+  .wd-nav-method-post {
+    background: color-mix(in srgb, #2563eb 15%, transparent);
+    color: #2563eb;
+  }
+  .wd-nav-method-put {
+    background: color-mix(in srgb, #9333ea 15%, transparent);
+    color: #9333ea;
+  }
+  .wd-nav-method-patch {
+    background: color-mix(in srgb, #d97706 15%, transparent);
+    color: #d97706;
+  }
+  .wd-nav-method-delete {
+    background: color-mix(in srgb, #dc2626 15%, transparent);
+    color: #dc2626;
+  }
+  .wd-nav-method-other {
+    background: var(--wd-surface);
+    color: var(--wd-text-muted);
+  }
+  .wd-nav-link-leaf {
+    display: flex !important;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+  }
+  .wd-nav-external-icon {
+    flex-shrink: 0;
+    color: var(--wd-text-muted);
+  }
+
+  /* Depth >= 1 group: a collapsible row that looks like a page link. */
+  .wd-nav-collapsible details {
+    margin: 0;
+  }
+  .wd-nav-collapsible summary {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    padding: 0.2rem 0.75rem;
+    margin: 0.1rem 0;
+    border-radius: 0 0.4rem 0.4rem 0;
+    cursor: pointer;
+    color: var(--wd-text-muted);
+    font-size: 0.9rem;
+    list-style: none;
+  }
+  .wd-nav-collapsible summary::-webkit-details-marker {
+    display: none;
+  }
+  .wd-nav-collapsible summary::marker {
+    content: "";
+  }
+  /* Same primary-tinted hover as a plain page link above. */
+  .wd-nav-collapsible summary:hover {
+    background: color-mix(in srgb, var(--wd-primary) 6%, transparent);
+    color: var(--wd-text);
+  }
+  /* When the group's own attached page is the current page, the pill
+     background lives on <summary> itself (not the inner <a> below,
+     which is deliberately stripped of its own background/padding so the
+     chevron can share the row) - otherwise only the label text would be
+     highlighted, leaving the chevron sitting outside the pill. This is
+     the same background/radius a plain `.wd-nav-list a.active` pill
+     uses, so an active group header looks identical to an active leaf
+     page row instead of falling back to text-only bold+color. */
+  .wd-nav-collapsible summary.active {
+    background: color-mix(in srgb, var(--wd-primary) 12%, transparent);
+    border-left: 1px solid var(--wd-primary);
+  }
+
+  .wd-nav-collapsible summary.active > a {
+    border-left: none;
+  }
+  /* Overrides `.wd-nav-list a`'s own block/padding - the row's padding is
+     owned by <summary> now, the label inside is just flex content. Wins
+     on specificity (class + 2 tags vs class + 1 tag) regardless of
+     source order. */
+  .wd-nav-collapsible summary a,
+  .wd-nav-collapsible summary .wd-nav-group-label {
+    display: block;
+    padding: 0;
+    border-radius: 0;
+    background: none;
+    color: inherit;
+    font-weight: inherit;
+    flex: 1;
+    min-width: 0;
+  }
+  .wd-nav-collapsible summary a:hover {
+    background: none;
+    color: var(--wd-text);
+  }
+  .wd-nav-collapsible summary a.active {
+    background: none;
+    color: var(--wd-primary);
+    font-weight: 500;
+  }
+  .wd-nav-chevron {
+    flex-shrink: 0;
+    color: var(--wd-text-muted);
+    transition: transform 0.15s ease;
+  }
+  .wd-nav-collapsible details[open] > summary .wd-nav-chevron {
+    transform: rotate(90deg);
+  }
+</style>

package/src/layout/components/SearchModal.astro

@@ -0,0 +1,42 @@
+---
+// The Pagefind-backed search overlay/modal - opened by TopBar.astro's own
+// `.wd-search-trigger` button (⌘K/Ctrl K also works, see
+// src/scripts/search.ts) from anywhere on the site. Fully self-contained:
+// takes no props, since none of its own markup depends on writedocs.json
+// config - unlike every other component split out of BaseLayout.astro.
+// Always rendered regardless of a page's `mode` (including 'blank'), so
+// search stays reachable via the keyboard shortcut even on a page with no
+// visible trigger button to click.
+//
+// Split out of BaseLayout.astro, which had grown to ~2200 lines covering
+// several unrelated concerns in one file - see that component's own
+// comment for the fuller rationale.
+import '../styles/search-modal.css';
+---
+<div class="wd-search-overlay" id="wd-search-overlay" hidden>
+  <div class="wd-search-modal" role="dialog" aria-modal="true" aria-label="Search">
+    <div class="wd-search-input-row">
+      <svg class="wd-search-icon" width="16" height="16" viewBox="0 0 14 14" aria-hidden="true">
+        <circle cx="6" cy="6" r="4.5" stroke="currentColor" stroke-width="1.4" fill="none" />
+        <path d="M9.5 9.5L13 13" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" />
+      </svg>
+      <input
+        type="text"
+        class="wd-search-input"
+        id="wd-search-input"
+        placeholder="Search docs..."
+        autocomplete="off"
+        autocapitalize="off"
+        spellcheck="false"
+      />
+      <kbd class="wd-search-esc">Esc</kbd>
+    </div>
+    <div class="wd-search-results" id="wd-search-results"></div>
+  </div>
+</div>
+<script>
+  import { initSearch } from '../../scripts/search';
+
+  initSearch(document);
+  document.addEventListener('astro:page-load', () => initSearch(document));
+</script>

package/src/layout/components/Sidebar.astro

@@ -0,0 +1,122 @@
+---
+import type { NavTreeNode } from "../../lib/config";
+import NavTree from "./NavTree.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
+// are named by the mark's own ink color instead, and the darker one
+// (wd_watermark_dark.png) is actually the better-contrast choice
+// against the light theme's near-white background, while the lighter,
+// unsuffixed one reads better against the dark theme's near-black one.
+// Imported (not referenced by string path) since this is a
+// framework-bundled asset living in src/assets, not something any
+// individual site's own public/ folder provides - astro.config.mjs
+// points publicDir at the site's public/ instead, so a plain <img
+// src="/..."> here would 404 on every real site build.
+import watermarkForLightTheme from "../../assets/wd_watermark_dark.png";
+import watermarkForDarkTheme from "../../assets/wd_watermark.png";
+
+// Deploy-time-only opt-out, not a writedocs.json field: a site's own writedocs.json
+// is part of its checked-in content (something the author controls), while
+// this is meant to be set by whatever's actually running the build (CI,
+// hosting platform env config, etc.) without touching that content - the
+// same reasoning as WRITEDOCS_CONTENT_DIR/WRITEDOCS_PACKAGE_ROOT already
+// being plain process.env reads rather than config fields (see
+// astro.config.mjs and this component's sibling files). Any value other
+// than the literal string "true" leaves the watermark showing, so an
+// unset/misspelled var fails toward the visible, "unmodified" default
+// rather than silently hiding it.
+const watermarkDisabled = process.env.WRITEDOCS_DISABLE_WATERMARK === "true";
+
+interface Props {
+  navTree: NavTreeNode[];
+  hrefForSlug: (slug: string) => string;
+  currentSlug: string;
+}
+const { navTree, hrefForSlug, currentSlug } = Astro.props as Props;
+---
+
+<nav class="wd-sidebar">
+  <NavTree nodes={navTree} hrefForSlug={hrefForSlug} currentSlug={currentSlug} />
+  {!watermarkDisabled && (
+    <div class="wd-sidebar-watermark">
+      <img src={watermarkForLightTheme.src} alt="Powered by writedocs" class="wd-watermark-light" />
+      <img src={watermarkForDarkTheme.src} alt="Powered by writedocs" class="wd-watermark-dark" />
+    </div>
+  )}
+</nav>
+<style>
+  /* 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
+     unstick and get carried away by the page's own scroll once
+     .wd-sidebar-col's bottom edge passed the viewport). max-height caps
+     it to the visible area below the topbar and overflow-y gives it an
+     independent scrollbar, so the page scrolls its content while the
+     sidebar scrolls itself - same treatment TableOfContents.astro's
+     .wd-toc already has (deliberately matching its `top`/`max-height`
+     values exactly, so both columns start scrolling at the same height
+     when a page has both). Reset back to normal (non-sticky, no cap) on
+     narrow screens in BaseLayout.astro's `@media (max-width: 860px)`
+     block, where the sidebar stacks full-width above the content instead
+     of sitting beside it. */
+  .wd-sidebar {
+    padding: 1.5rem 1rem 1.5rem 0;
+    position: sticky;
+    /* --wd-topbar-offset (src/scripts/topbar-offset.ts) is the topbar's
+       real measured height - a fixed 5rem (this var()'s own fallback)
+       only matched the topbar's simplest, single-row case; matched
+       exactly by TableOfContents.astro's own .wd-toc, see this file's
+       own comment above on why that pairing matters. */
+    top: var(--wd-topbar-offset, 5rem);
+    max-height: calc(100vh - var(--wd-topbar-offset, 5rem));
+    overflow-y: auto;
+  }
+  /* Desktop only (see the :global(.wd-sidebar-col) guard) - turns the
+     sidebar into a fixed-height flex column so .wd-sidebar-watermark's
+     margin-top: auto below can push it all the way to the bottom of the
+     visible area when the nav tree doesn't fill it, instead of sitting
+     right after the last nav item with a gap of empty space beneath it.
+     height (not just the max-height above) is what makes this work -
+     max-height alone only caps how tall the box *can* get, it doesn't
+     force it to actually be that tall when content is shorter, which is
+     exactly the "empty space below the watermark" case this replaces.
+     Scoped to .wd-sidebar-col specifically (not the plain .wd-sidebar
+     this component always renders) so the *reused* copy inside
+     MobileMenu.astro's own scrollable panel is untouched - forcing a
+     tall fixed height there would leave an awkward blank stretch inside
+     the mobile drawer under a short nav list, where "pinned to the
+     bottom of the screen" isn't really representative of a panel the
+     reader can already see the bottom of by scrolling. */
+  :global(.wd-sidebar-col) .wd-sidebar {
+    height: calc(100vh - var(--wd-topbar-offset, 5rem));
+    display: flex;
+    flex-direction: column;
+  }
+  /* Last thing in the nav column. margin-top: auto only has real estate
+     to push into on desktop (where the rule above gives .wd-sidebar a
+     real fixed height) - inside the mobile menu's reused copy, .wd-
+     sidebar is never a flex container, so this margin resolves to 0 and
+     the watermark just falls in after the last nav item instead, same
+     as before that rule existed. Either way, padding-top + border-top
+     stay unconditional, so there's always at least that much separation
+     from the nav items above it. */
+  .wd-sidebar-watermark {
+    margin-top: auto;
+    padding-top: 1rem;
+    border-top: 1px solid var(--wd-border);
+  }
+  /* No `display` here - that's the base.css wd-watermark-light/-dark
+     toggle's job alone (default display:none on the inactive one,
+     display:block on the active one). This rule's own selector
+     specificity (a class + an attribute-scoping selector + a type
+     selector) is higher than that toggle's plain single/double-class
+     rules, so a `display: block` here would win the cascade
+     unconditionally on BOTH images regardless of [data-theme] -
+     exactly the "both always visible" bug this replaces. */
+  .wd-sidebar-watermark img {
+    height: 14px;
+    width: auto;
+    opacity: 0.7;
+  }
+</style>

package/src/layout/components/SiteFooter.astro

@@ -0,0 +1,85 @@
+---
+// writedocs.json's `footer.columns`/`socials` - see footerSchema/`socials` in
+// lib/config.ts. Renders nothing at all (not even an empty bordered band)
+// when a site hasn't configured either - both fields default to empty, so
+// `hasFooterContent` is never undefined either way. Callers don't need to
+// check this themselves; this component decides on its own whether it has
+// anything to show.
+//
+// Split out of BaseLayout.astro, which had grown to ~2200 lines covering
+// several unrelated concerns in one file - see that component's own
+// comment for the fuller rationale.
+import { isExternalHref, type DocsConfig } from '../../lib/config';
+import AppIcon from '../../components/AppIcon.astro';
+import '../styles/footer.css';
+
+interface Props {
+  config: DocsConfig;
+  logoLight?: string;
+  logoDark?: string;
+}
+const { config, logoLight, logoDark } = Astro.props as Props;
+const hasLogoImage = Boolean(logoLight || logoDark);
+const socialEntries = Object.entries(config.socials);
+// A `socials` key doubles as its own icon reference (resolveIcon() in
+// lib/config.ts, via <AppIcon>) - fine as-is for a bare name like
+// "github", but a key using the explicit "collection:icon-name" form
+// (e.g. "simple-icons:discord", for a platform Lucide doesn't have a
+// matching icon for) would otherwise end up as this link's own aria-label
+// verbatim, colon and all - not what a screen reader user wants read
+// aloud. Strips down to just the part after the last colon for the label
+// specifically; the full key still goes to AppIcon unchanged.
+const socialLabel = (platform: string) => platform.split(':').pop() ?? platform;
+const hasFooterContent = config.footer.columns.length > 0 || socialEntries.length > 0;
+---
+{hasFooterContent && (
+  <footer class="wd-footer">
+    <div class="wd-footer-inner">
+      {hasLogoImage && (
+        <a class="wd-footer-brand" href="/">
+          {logoLight && <img src={logoLight} alt={config.name} height="24" class="wd-logo-light" />}
+          {logoDark && <img src={logoDark} alt={config.name} height="24" class="wd-logo-dark" />}
+        </a>
+      )}
+      {config.footer.columns.length > 0 && (
+        <div class="wd-footer-columns">
+          {config.footer.columns.map((column) => (
+            <div class="wd-footer-column">
+              {column.title && <div class="wd-footer-column-title">{column.title}</div>}
+              <ul class="wd-footer-column-links">
+                {column.links.map((link) => (
+                  <li>
+                    <a
+                      href={link.href}
+                      target={isExternalHref(link.href) ? '_blank' : undefined}
+                      rel={isExternalHref(link.href) ? 'noopener noreferrer' : undefined}
+                      aria-label={!link.label ? link.icon : undefined}
+                    >
+                      <AppIcon icon={link.icon} class="wd-tab-icon" />
+                      {link.label}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </div>
+      )}
+      {socialEntries.length > 0 && (
+        <div class="wd-footer-socials">
+          {socialEntries.map(([platform, url]) => (
+            <a
+              href={url}
+              class="wd-footer-social-link"
+              aria-label={socialLabel(platform)}
+              target={isExternalHref(url) ? '_blank' : undefined}
+              rel={isExternalHref(url) ? 'noopener noreferrer' : undefined}
+            >
+              <AppIcon icon={platform} class="wd-footer-social-icon" />
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  </footer>
+)}