@writedocs/generator 0.1.0

package/src/layout/components/TableOfContents.astro

@@ -0,0 +1,117 @@
+---
+export interface TocHeading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface Props {
+  headings: TocHeading[];
+}
+
+const { headings } = Astro.props as Props;
+---
+{headings.length > 0 && (
+  <nav class="wd-toc" aria-label="On this page">
+    <div class="wd-toc-title">On this page</div>
+    <ul>
+      {headings.map((h) => (
+        <li class={`wd-toc-item wd-toc-level-${h.depth}`}>
+          <a href={`#${h.slug}`} data-toc-slug={h.slug}>{h.text}</a>
+        </li>
+      ))}
+    </ul>
+  </nav>
+)}
+
+<script>
+  function initToc(root: ParentNode) {
+    const tocLinks = Array.from(root.querySelectorAll<HTMLAnchorElement>('.wd-toc a[data-toc-slug]'));
+    if (tocLinks.length === 0) return;
+
+    const headingEls = tocLinks
+      .map((link) => document.getElementById(link.dataset.tocSlug ?? ''))
+      .filter((el): el is HTMLElement => el !== null);
+
+    if (headingEls.length === 0) return;
+
+    const linkBySlug = new Map(tocLinks.map((link) => [link.dataset.tocSlug, link]));
+
+    const setActive = (slug: string | null) => {
+      tocLinks.forEach((link) => link.classList.remove('active'));
+      if (slug) linkBySlug.get(slug)?.classList.add('active');
+    };
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // Pick the topmost heading currently intersecting the "active band"
+        // near the top of the viewport, rather than whichever fires last -
+        // IntersectionObserver doesn't guarantee entries arrive in DOM order.
+        const visible = entries
+          .filter((e) => e.isIntersecting)
+          .map((e) => e.target as HTMLElement);
+        if (visible.length > 0) {
+          const topMost = visible.reduce((a, b) =>
+            a.getBoundingClientRect().top < b.getBoundingClientRect().top ? a : b
+          );
+          setActive(topMost.id);
+        }
+      },
+      { rootMargin: '0px 0px -70% 0px', threshold: 1.0 }
+    );
+
+    headingEls.forEach((el) => observer.observe(el));
+  }
+
+  initToc(document);
+  document.addEventListener('astro:page-load', () => initToc(document));
+</script>
+
+<style>
+  /* top/max-height deliberately match Sidebar.astro's own .wd-sidebar
+     values exactly (see its comment) - both driven by --wd-topbar-offset
+     (src/scripts/topbar-offset.ts), the topbar's real measured height. */
+  .wd-toc {
+    position: sticky;
+    top: var(--wd-topbar-offset, 5rem);
+    padding: 1.5rem 1rem 1.5rem 1.5rem;
+    font-size: 0.85rem;
+    max-height: calc(100vh - var(--wd-topbar-offset, 5rem));
+    overflow-y: auto;
+  }
+  .wd-toc-title {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--wd-text-muted);
+    margin-bottom: 0.6rem;
+  }
+  .wd-toc ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    border-left: 1px solid var(--wd-border);
+  }
+  .wd-toc-item a {
+    display: block;
+    padding: 0.3rem 0 0.3rem 0.85rem;
+    margin-left: -1px;
+    border-left: 2px solid transparent;
+    text-decoration: none;
+    color: var(--wd-text-muted);
+    line-height: 1.4;
+  }
+  .wd-toc-level-3 a {
+    padding-left: 1.6rem;
+    font-size: 0.82rem;
+  }
+  .wd-toc-item a:hover {
+    color: var(--wd-text);
+  }
+  .wd-toc-item a.active {
+    color: var(--wd-primary);
+    border-left-color: var(--wd-primary);
+    font-weight: 500;
+  }
+</style>

package/src/layout/components/TopBar.astro

@@ -0,0 +1,311 @@
+---
+// The site's persistent header: brand, version/language/product switchers,
+// tabs + global dropdowns (second row), writedocs.json's `topbar.links` (as a
+// plain row above 860px, collapsed into a single ellipsis dropdown below
+// it), the search trigger, and the theme toggle. Also renders the
+// hamburger button that opens MobileMenu.astro's own drawer - the button
+// itself lives here (it's positioned as the first child of
+// .wd-topbar-inner, part of this row), the panel it opens is a separate
+// component/file.
+//
+// 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, type Selector, type GlobalDropdownView } from '../../lib/config';
+import AppIcon from '../../components/AppIcon.astro';
+import '../styles/dropdown.css';
+import '../styles/topbar.css';
+
+interface Props {
+  config: DocsConfig;
+  // 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.
+  selectors: Selector[];
+  // The always-visible topbar dropdown list from navigation.global.dropdowns.
+  globalDropdowns: GlobalDropdownView[];
+  // Whether this page would show a sidebar at all (mode === 'default' or
+  // 'wide') - gates whether the hamburger toggle renders, same condition
+  // MobileMenu.astro itself is gated on for the panel it opens.
+  showSidebarCol: boolean;
+  logoLight?: string;
+  logoDark?: string;
+  brandLabel?: string;
+}
+const { config, selectors, globalDropdowns, showSidebarCol, logoLight, logoDark, brandLabel } = Astro.props as Props;
+
+// The topbar is two stacked rows, matching Mintlify's own layout: a top
+// row with the brand and the "pick one" switchers (versions/languages/
+// products, or a dropdown used as a nested path segment) on the right,
+// and a second row underneath for tabs plus the always-visible global
+// dropdowns - both of which behave like a row of labeled links rather
+// than a single current-value switcher.
+//
+// A dropdown container nested directly inside a tab (writedocs.json's "API
+// Reference" tab having a `dropdowns` array instead of `pages`) reads as
+// part of that tab's own local navigation, not as an independent
+// top-level "pick one" choice - it's rendered by turning the *tab's own
+// pill* into a dropdown-trigger (see SelectorOption.dropdown /
+// buildSelectors() in lib/config.ts, and the tabSelectors.map below),
+// rather than as a separate control. So unlike a root-level dropdown/
+// version/language/product selector (which does surface as a brand-row
+// switcher), this one is dropped from switcherSelectors entirely -
+// `selectors` is in root-to-leaf path order, so "nested directly inside a
+// tab" just means the previous entry in the array is the 'tab' selector.
+const switcherSelectors = selectors.filter(
+  (sel, i) => sel.kind !== 'tab' && !(sel.kind === 'dropdown' && selectors[i - 1]?.kind === 'tab')
+);
+const tabSelectors = selectors.filter((sel) => sel.kind === 'tab');
+const showSecondRow = tabSelectors.length > 0 || globalDropdowns.length > 0;
+---
+<header class="wd-topbar">
+  <div class="wd-topbar-row wd-topbar-row-brand">
+    <div class="wd-topbar-inner">
+      {/* Only rendered on pages that would show a sidebar at all
+          (showSidebarCol - same condition MobileMenu.astro's own
+          rendering is gated on). Hidden entirely above 860px via CSS
+          (.wd-mobile-menu-toggle's own media query in topbar.css), not
+          JS - so there's no flash-of-hamburger on a desktop-width load. */}
+      {showSidebarCol && (
+        <button
+          type="button"
+          class="wd-mobile-menu-toggle"
+          aria-label="Open menu"
+          aria-expanded="false"
+          aria-controls="wd-mobile-menu"
+          data-mobile-menu-trigger
+        >
+          <svg class="wd-mobile-menu-icon wd-mobile-menu-icon-bars" width="18" height="18" viewBox="0 0 18 18" aria-hidden="true">
+            <path d="M2.5 5H15.5M2.5 9H15.5M2.5 13H15.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+          </svg>
+          <svg class="wd-mobile-menu-icon wd-mobile-menu-icon-close" width="18" height="18" viewBox="0 0 18 18" aria-hidden="true">
+            <path d="M4 4L14 14M14 4L4 14" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+          </svg>
+        </button>
+      )}
+      <a class="wd-topbar-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" />}
+        {brandLabel && <span>{brandLabel}</span>}
+      </a>
+
+      {switcherSelectors.length > 0 && (
+        <nav class="wd-topbar-switchers" aria-label="Version, language and product selection">
+          {switcherSelectors.map((sel) => {
+            // versions / languages / products, and a dropdown used as a
+            // nested path segment, all render as a single switcher: the
+            // trigger shows the *current* option, the menu lists the
+            // alternatives - unlike tabs, where every option is its own
+            // always-visible pill in the row below.
+            const current = sel.options.find((o) => o.active) ?? sel.options[0];
+            return (
+              <div class="wd-dropdown" data-selector-kind={sel.kind}>
+                <button type="button" class="wd-dropdown-trigger wd-switcher-trigger" aria-haspopup="true" aria-expanded="false">
+                  <AppIcon icon={current.icon} class="wd-tab-icon" />
+                  {current.label}
+                  {current.tag && <span class="wd-selector-tag">{current.tag}</span>}
+                  <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                    <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+                  </svg>
+                </button>
+                <div class="wd-dropdown-menu" role="menu">
+                  <div class="wd-dropdown-menu-panel">
+                    {sel.options.map((opt) => (
+                      <a
+                        href={opt.href}
+                        role="menuitem"
+                        class={opt.active ? 'active' : ''}
+                        target={isExternalHref(opt.href) ? '_blank' : undefined}
+                        rel={isExternalHref(opt.href) ? 'noopener noreferrer' : undefined}
+                      >
+                        <AppIcon icon={opt.icon} class="wd-tab-icon" />
+                        {opt.label}
+                        {opt.tag && <span class="wd-selector-tag">{opt.tag}</span>}
+                      </a>
+                    ))}
+                  </div>
+                </div>
+              </div>
+            );
+          })}
+        </nav>
+      )}
+
+      <nav class="wd-topbar-links">
+        {config.topbar.links.map((link) => (
+          <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>
+        ))}
+      </nav>
+
+      {/* Below 860px, .wd-topbar-links above is hidden (see topbar.css)
+          and this takes its place instead - same link set, same
+          writedocs.json config.topbar.links, just collapsed behind a single
+          icon button rather than an inline row of text links that would
+          otherwise wrap and eat vertical space next to the brand. Reuses
+          the existing .wd-dropdown/.wd-dropdown-trigger/.wd-dropdown-menu/
+          .wd-dropdown-menu-panel pattern (see the switcher/tab dropdowns
+          above) rather than inventing a new toggle mechanism -
+          initDropdowns() (src/scripts/dropdowns.ts, wired below) already
+          wires up every .wd-dropdown on the page generically, so this
+          needs no JS of its own. */}
+      {config.topbar.links.length > 0 && (
+        <div class="wd-dropdown wd-topbar-links-mobile" data-selector-kind="topbar-links">
+          <button
+            type="button"
+            class="wd-dropdown-trigger wd-topbar-links-toggle"
+            aria-haspopup="true"
+            aria-expanded="false"
+            aria-label="More links"
+          >
+            <svg width="4" height="16" viewBox="0 0 4 16" aria-hidden="true">
+              <circle cx="2" cy="2" r="1.7" fill="currentColor" />
+              <circle cx="2" cy="8" r="1.7" fill="currentColor" />
+              <circle cx="2" cy="14" r="1.7" fill="currentColor" />
+            </svg>
+          </button>
+          <div class="wd-dropdown-menu" role="menu">
+            <div class="wd-dropdown-menu-panel">
+              {config.topbar.links.map((link) => (
+                <a
+                  href={link.href}
+                  role="menuitem"
+                  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>
+              ))}
+            </div>
+          </div>
+        </div>
+      )}
+
+      <button type="button" class="wd-search-trigger" aria-label="Search" data-search-trigger>
+        <svg class="wd-search-icon" width="14" height="14" 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>
+        <span class="wd-search-placeholder">Search...</span>
+        <kbd class="wd-search-kbd">⌘K</kbd>
+      </button>
+
+      <button type="button" class="wd-theme-toggle" aria-label="Toggle color theme">
+        <AppIcon icon="sun" class="wd-theme-icon wd-theme-icon-sun" />
+        <AppIcon icon="moon" class="wd-theme-icon wd-theme-icon-moon" />
+      </button>
+    </div>
+  </div>
+
+  {showSecondRow && (
+    <div class="wd-topbar-row wd-topbar-row-tabs">
+      <div class="wd-topbar-inner">
+        <nav class="wd-topbar-tabs" aria-label="Sections">
+          {tabSelectors.map((sel) =>
+            sel.options.map((opt) =>
+              opt.dropdown ? (
+                // A tab whose own content is `dropdowns` (not `pages`)
+                // renders as a dropdown-trigger in place of the plain
+                // pill - the tab's own label/icon stay on the trigger
+                // (not "whichever dropdown is current", so it reads as
+                // "this tab, which happens to expand" rather than
+                // jumping around as you navigate its sub-pages), and its
+                // dropdowns become the menu.
+                <div class="wd-dropdown" data-selector-kind="tab">
+                  <button
+                    type="button"
+                    class={`wd-dropdown-trigger wd-tab-link ${opt.active ? 'active' : ''}`}
+                    aria-haspopup="true"
+                    aria-expanded="false"
+                  >
+                    <AppIcon icon={opt.icon} class="wd-tab-icon" />
+                    {opt.label}
+                    <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                      <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+                    </svg>
+                  </button>
+                  <div class="wd-dropdown-menu" role="menu">
+                    <div class="wd-dropdown-menu-panel">
+                      {opt.dropdown.map((d) => (
+                        <a
+                          href={d.href}
+                          role="menuitem"
+                          class={d.active ? 'active' : ''}
+                          target={isExternalHref(d.href) ? '_blank' : undefined}
+                          rel={isExternalHref(d.href) ? 'noopener noreferrer' : undefined}
+                        >
+                          <AppIcon icon={d.icon} class="wd-tab-icon" />
+                          {d.label}
+                        </a>
+                      ))}
+                    </div>
+                  </div>
+                </div>
+              ) : (
+                <a
+                  href={opt.href}
+                  class={`wd-tab-link ${opt.active ? 'active' : ''}`}
+                  target={isExternalHref(opt.href) ? '_blank' : undefined}
+                  rel={isExternalHref(opt.href) ? 'noopener noreferrer' : undefined}
+                >
+                  <AppIcon icon={opt.icon} class="wd-tab-icon" />
+                  {opt.label}
+                </a>
+              )
+            )
+          )}
+          {globalDropdowns.map((d) =>
+            d.href !== null ? (
+              <a
+                href={d.href}
+                class="wd-tab-link"
+                target={isExternalHref(d.href) ? '_blank' : undefined}
+                rel={isExternalHref(d.href) ? 'noopener noreferrer' : undefined}
+              >
+                <AppIcon icon={d.icon} class="wd-tab-icon" />
+                {d.label}
+              </a>
+            ) : (
+              <div class="wd-dropdown">
+                <button type="button" class="wd-dropdown-trigger" aria-haspopup="true" aria-expanded="false">
+                  <AppIcon icon={d.icon} class="wd-tab-icon" />
+                  {d.label}
+                  <svg class="wd-dropdown-caret" width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+                    <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" stroke-width="1.4" fill="none" stroke-linecap="round" stroke-linejoin="round" />
+                  </svg>
+                </button>
+                <div class="wd-dropdown-menu" role="menu">
+                  <div class="wd-dropdown-menu-panel">
+                    {d.items.map((item) => (
+                      <a href={item.href} role="menuitem" class={item.active ? 'active' : ''}>{item.label}</a>
+                    ))}
+                  </div>
+                </div>
+              </div>
+            )
+          )}
+        </nav>
+      </div>
+    </div>
+  )}
+</header>
+<script>
+  import { initDropdowns } from '../../scripts/dropdowns';
+  import { initThemeToggle } from '../../scripts/theme-toggle';
+
+  initDropdowns(document);
+  initThemeToggle(document);
+  document.addEventListener('astro:page-load', () => {
+    initDropdowns(document);
+    initThemeToggle(document);
+  });
+</script>

package/src/layout/styles/banner.css

@@ -0,0 +1,44 @@
+/* writedocs.json's `banner` - see bannerSchema in lib/config.ts. Markup stays
+   inline in BaseLayout.astro (it's tiny, and its own [data-banner-dismissed]
+   flash-prevention script already lives there) - this is just its styling,
+   split out for the same organizational reasons as every other file in
+   this directory. Sits above .wd-topbar, full-width, no max-width wrapper -
+   a banner reads as a site-wide strip, not page content, so it shouldn't
+   line up with .wd-shell's centered column. Hidden via the
+   [data-banner-dismissed] attribute set by BaseLayout's own inline <head>
+   script rather than a client-side mount check, so a previously-dismissed
+   banner never flashes visible before JS runs - same technique as the
+   [data-theme] flash-prevention script. */
+:root[data-banner-dismissed='true'] .wd-banner {
+  display: none;
+}
+.wd-banner {
+  width: 100%;
+}
+.wd-banner-info { background: var(--wd-primary); color: #fff; }
+.wd-banner-warning { background: #b45309; color: #fff; }
+.wd-banner-critical { background: #b91c1c; color: #fff; }
+.wd-banner-inner {
+  max-width: 1440px;
+  margin: 0 auto;
+  padding: 0.6rem 1.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  font-size: 0.88rem;
+  text-align: center;
+}
+.wd-banner-content { flex: 1; }
+.wd-banner-dismiss {
+  flex-shrink: 0;
+  border: none;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font-size: 1.1rem;
+  line-height: 1;
+  padding: 0 0.25rem;
+  opacity: 0.85;
+}
+.wd-banner-dismiss:hover { opacity: 1; }