@writedocs/generator 0.1.0

package/src/layout/styles/base.css

@@ -0,0 +1,234 @@
+/* Base element styles + the .wd-shell three-column layout (sidebar / main
+   / toc) - imported once by BaseLayout.astro. Everything here consumes the
+   semantic --wd-* custom properties (--wd-primary, --wd-background, etc.)
+   set on :root by BaseLayout's own inline <style define:vars> block, not
+   the raw wdPrimaryLight/wdPrimaryDark values themselves - so, unlike that
+   block, none of this needs to live inside an .astro file's own scoped
+   <style> to work. A plain imported .css file is never scoped by Astro in
+   the first place, so every selector below is already effectively global -
+   no :global() wrapper needed (and, if left in by mistake, :global(...) is
+   not valid CSS outside Astro's own scoped-<style> processing, so a rule
+   written that way here would just silently never match anything). */
+
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  /* Sticky-footer layout: body is the flex column, .wd-page (everything
+     above the footer - banner/topbar/.wd-shell, see BaseLayout.astro) is
+     its flex: 1 0 auto item below, and <footer class="wd-footer"> is a
+     plain sibling after it - on a page short enough not to need
+     scrolling, .wd-page's flex-grow fills the leftover space down to the
+     viewport's bottom edge, pushing the footer flush against it (rather
+     than the footer trailing right after a half-empty page with its own
+     background peeking through beneath it); on a page tall enough to
+     already fill/exceed the viewport, .wd-page just settles at its own
+     natural (larger) height and the footer trails normally at the real
+     end of the document, exactly as before this rule existed. Doesn't
+     apply in `mode: "blank"` (no .wd-page wrapper, no footer at all in
+     that branch - see BaseLayout.astro) - a blank page already controls
+     100% of its own layout.
+  */
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  /* theme.background (writedocs.json) - --wd-page-bg-color/--wd-page-bg-image
+     default to the same value as --wd-background/'none' (see
+     BaseLayout.astro's lightPageBgColor/lightPageBgImage resolution), so
+     an unconfigured site renders identically to a plain background: var(
+     --wd-background) rule. background-attachment: fixed keeps a
+     configured image sized to the viewport rather than the full
+     (possibly very tall) document - the more expected look for a
+     decorative page background, not something that stretches/tiles
+     across a long scrolling doc. The topbar and footer each get their
+     own explicit opaque background (topbar.css, footer.css)
+     specifically so this doesn't show through them - the sidebar, main
+     content, and toc columns all have no background of their own, so a
+     configured page background/image shows through all three. */
+  background-color: var(--wd-page-bg-color);
+  background-image: var(--wd-page-bg-image);
+  background-size: cover;
+  background-position: center;
+  background-repeat: no-repeat;
+  background-attachment: fixed;
+  color: var(--wd-text);
+  /* --wd-font-family-body/--wd-font-family (BaseLayout.astro's own
+     define:vars <style> block, driven by theme.fonts - see
+     resolveFonts()/fontsSchema in lib/config.ts) are always both set to a
+     real, already-resolved font stack, never left for this rule's own
+     fallback to cover - an unconfigured site still resolves to Inter here
+     (genuinely loaded via a Google Fonts <link>, not just named as a
+     fallback the way this line used to work before theme.fonts existed).
+     The literal fallback stack below only matters in the narrow window
+     before that <style> block itself has been parsed. */
+  font-family: var(--wd-font-family-body, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif);
+  line-height: 1.6;
+}
+a {
+  color: var(--wd-primary);
+}
+/* theme.fonts.heading (or the site-wide theme.fonts.family/Inter default,
+   when no heading-specific override is configured - see
+   --wd-font-family-heading's own resolution in BaseLayout.astro) - applies
+   everywhere a heading renders (article prose, the auto-generated
+   .wd-article-header h1, etc.), not just inside .wd-article specifically,
+   since nothing site-wide should render headings in a different font by
+   accident just because it happens to sit outside that one container. */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: var(--wd-font-family-heading, inherit);
+}
+code {
+  background: var(--wd-surface);
+  border: 1px solid var(--wd-border);
+  padding: 0.15em 0.45em;
+  border-radius: 0.35em;
+  font-size: 1em;
+  font-weight: 500;
+}
+pre code {
+  background: none;
+  border: none;
+  padding: 0;
+  font-weight: normal;
+}
+pre {
+  padding: 1rem;
+  border-radius: 0.5rem;
+  overflow-x: auto;
+}
+
+/* flex: 1 0 auto (not the shorthand `flex: 1` main.wd-shell below also
+   uses) so this never shrinks below its own natural content height even
+   inside a flex *column* ancestor shorter than that - see body's own
+   comment above for the sticky-footer layout this is the growing half
+   of. */
+.wd-page {
+  display: flex;
+  flex-direction: column;
+  flex: 1 0 auto;
+}
+.wd-shell {
+  display: flex;
+  max-width: 1440px;
+  margin: 0 auto;
+  width: 100%;
+  /* Grows to fill .wd-page's remaining height (after the banner/topbar
+     above it take their own natural height) on a short page - see body's
+     comment above. .wd-sidebar-col/.wd-toc-col below then stretch to
+     match *this* element's own height for free, via flexbox's own
+     default `align-items: stretch` on a row - no min-height of their own
+     needed (this replaces one on .wd-sidebar-col that used to hardcode
+     100vh instead, which overshot on a page with a banner/tall topbar
+     above it, or undershot the real page height on a page taller than
+     one viewport). */
+  flex: 1;
+}
+.wd-sidebar-col {
+  width: 260px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--wd-border);
+}
+.wd-main-col {
+  flex: 1;
+  min-width: 0;
+}
+.wd-toc-col {
+  width: 230px;
+  flex-shrink: 0;
+  border-left: 1px solid var(--wd-border);
+}
+@media (max-width: 1150px) {
+  .wd-toc-col {
+    display: none;
+  }
+}
+@media (max-width: 860px) {
+  .wd-shell {
+    flex-direction: column;
+  }
+  /* The sidebar itself no longer stacks full-width above the page content
+     at this width - it moved into MobileMenu.astro's own panel instead
+     (see its own <slot name="sidebar" /> copy), which renders its own
+     second copy of the same sidebar content. This copy (inside
+     .wd-sidebar-col) just disappears rather than being repositioned. */
+  .wd-sidebar-col {
+    display: none;
+  }
+  /* Sidebar.astro's .wd-sidebar is sticky-with-its-own-scrollbar on wide
+     screens (see its own style block for why) - not appropriate for the
+     copy now living inside MobileMenu.astro's own scroll area, which
+     already has its own scroll area; this makes it flow as a plain block
+     there instead of trying to run a second, nested one. This selector
+     reaches into Sidebar.astro's own scoped class from a plain external
+     stylesheet - works with no special syntax needed (unlike the
+     :global() wrapper this rule needed back when it lived in BaseLayout's
+     own scoped <style> block), since a plain .css file was never scoped
+     to begin with. */
+  .wd-sidebar {
+    position: static;
+    max-height: none;
+    overflow-y: visible;
+  }
+}
+
+/* Dual light/dark logo: both <img> tags are always in the markup (see
+   TopBar.astro/MobileMenu.astro/SiteFooter.astro, all three of which
+   render this same pair), CSS shows only the one matching the active
+   [data-theme] - set by the inline anti-FOUC script in BaseLayout's
+   <head> + the theme-toggle click handler (src/scripts/theme-toggle.ts).
+   A site that only gave one logo path gets the same <img> rendered twice
+   with both classes worth of visibility rules, i.e. it's just always
+   shown. Kept here (not co-located with any one of the three components
+   above) since all three need it identically. */
+.wd-logo-dark {
+  display: none;
+}
+[data-theme="dark"] .wd-logo-light {
+  display: none;
+}
+[data-theme="dark"] .wd-logo-dark {
+  display: block;
+}
+
+/* Same dual-image/CSS-toggle mechanism as the logo pair above, for the
+   "Powered by writedocs" sidebar watermark (Sidebar.astro) - kept as
+   plain global rules here rather than a `:global()`-wrapped selector
+   inside that component's own scoped <style> block, matching this
+   proven pattern exactly instead of a second, more exotic variant of
+   it. */
+.wd-watermark-dark {
+  display: none;
+}
+[data-theme="dark"] .wd-watermark-light {
+  display: none;
+}
+[data-theme="dark"] .wd-watermark-dark {
+  display: block;
+}
+
+/* Astro's Shiki output (both the built-in MDX code-fence pipeline,
+   configured with dual themes in astro.config.mjs, and the <Code />
+   component used for the API playground's request/response snippets)
+   bakes the "light" theme as each element's base color/background and
+   stashes the dark equivalents in --shiki-dark/--shiki-dark-bg custom
+   properties. Swapping to those on [data-theme='dark'] is the officially
+   documented way to make Shiki-highlighted code follow a manual
+   (non-media-query) theme toggle - see
+   https://docs.astro.build/en/guides/syntax-highlighting/#setting-light-and-dark-mode-themes.
+   Site-wide/article-content concern, unrelated to any one layout
+   component, which is why it lives here rather than in any of the
+   feature-specific stylesheets. */
+[data-theme="dark"] .astro-code,
+[data-theme="dark"] .astro-code span {
+  color: var(--shiki-dark) !important;
+  background-color: var(--shiki-dark-bg) !important;
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
+}

package/src/layout/styles/dropdown.css

@@ -0,0 +1,133 @@
+/* The .wd-dropdown/.wd-dropdown-trigger/.wd-dropdown-menu/
+   .wd-dropdown-menu-panel pattern below (plus initDropdowns() in
+   src/scripts/dropdowns.ts) is written to be reused by any component that
+   wants a click-to-toggle dropdown, not just the topbar selectors/tab
+   dropdowns it was first built for - CopyPageMenu.astro is another
+   consumer. Imported by TopBar.astro (which owns most of this markup:
+   switchers, tabs, the small-screen topbar.links ellipsis) and also by
+   MobileMenu.astro, for the .wd-tab-icon/.wd-selector-tag primitives its
+   own accordion rows reuse (MobileMenu doesn't render any .wd-dropdown
+   markup itself today, but importing this costs nothing extra - Vite
+   dedupes a CSS file imported from more than one component). */
+.wd-dropdown {
+  position: relative;
+}
+.wd-dropdown-trigger {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.4rem 0.75rem;
+  border-radius: 0.4rem;
+  border: none;
+  background: none;
+  cursor: pointer;
+  color: var(--wd-text-muted);
+  font-size: 0.9rem;
+  font-weight: 500;
+  font-family: inherit;
+}
+.wd-dropdown-trigger:hover {
+  color: var(--wd-text);
+}
+.wd-dropdown-caret {
+  transition: transform 0.12s ease;
+}
+.wd-topbar-tabs .wd-dropdown-caret {
+  margin-top: 4px;
+}
+.wd-dropdown.open .wd-dropdown-caret {
+  transform: rotate(180deg);
+}
+/* .wd-dropdown-menu itself sits flush against the trigger (top: 100%, no
+   gap) and is what actually receives :hover/.open - the visible white box
+   (background/border/shadow/padding) lives on the .wd-dropdown-menu-panel
+   child instead, offset down via padding-top on the parent. This is
+   deliberate: an earlier version put that 0.4rem breathing room directly
+   on .wd-dropdown-menu's own `top` offset, which left a dead strip between
+   the trigger and the menu that belonged to neither - moving the mouse
+   from one to the other crossed unhovered space and closed the menu
+   before you could reach it. Padding (unlike a `top`/`margin` offset) is
+   still part of the element's own hoverable box, so this keeps the same
+   visual gap without the dead zone. */
+.wd-dropdown-menu {
+  display: none;
+  position: absolute;
+  top: 100%;
+  left: 0;
+  padding-top: 0.4rem;
+  z-index: 20;
+}
+.wd-dropdown-menu-panel {
+  min-width: 180px;
+  background: var(--wd-background);
+  border: 1px solid var(--wd-border);
+  border-radius: 0.5rem;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
+  padding: 0.4rem;
+}
+.wd-dropdown.open .wd-dropdown-menu {
+  display: block;
+}
+/* Hovering a trigger reveals its menu too, not just clicking it - a plain
+   CSS :hover rule alongside the JS-driven .open class (initDropdowns()),
+   which still owns click-to-toggle/outside-click-to-close/Escape-to-close.
+   Both rules just set the same display:block, so they layer cleanly:
+   moving the mouse away closes a hover-only reveal, while a click-opened
+   menu (the .open class) stays open regardless of where the mouse is
+   until it's explicitly closed. */
+.wd-dropdown:hover .wd-dropdown-caret {
+  transform: rotate(180deg);
+}
+.wd-dropdown:hover .wd-dropdown-menu {
+  display: block;
+}
+.wd-dropdown-menu a {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.45rem 0.6rem;
+  border-radius: 0.35rem;
+  text-decoration: none;
+  color: var(--wd-text);
+  font-size: 0.88rem;
+}
+.wd-dropdown-menu a:hover {
+  background: var(--wd-surface);
+}
+.wd-dropdown-menu a.active {
+  color: var(--wd-primary);
+  background: color-mix(in srgb, var(--wd-primary) 10%, transparent);
+}
+
+/* .wd-tab-icon is shared by AppIcon's two render modes: a real <svg>
+   (astro-icon, sized to the surrounding text) or a <span> (literal
+   emoji/text, sized by inherited font-size alone). Used by every dropdown
+   option/trigger above, TopBar.astro's tabs row, MobileMenu.astro's own
+   accordion rows, topbar.links (both the desktop row and the collapsed
+   mobile dropdown - TopBar.astro), and footer column links
+   (SiteFooter.astro) - a generic "icon sized to sit next to text" primitive
+   despite the tab-specific name, not worth a same-rules second class. */
+svg.wd-tab-icon {
+  width: 1em;
+  height: 1em;
+  flex-shrink: 0;
+}
+span.wd-tab-icon {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+.wd-selector-tag {
+  font-size: 0.65rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  padding: 0.1rem 0.4rem;
+  border-radius: 999px;
+  background: var(--wd-surface);
+  color: var(--wd-text-muted);
+}
+.wd-dropdown-menu a.active .wd-selector-tag {
+  background: color-mix(in srgb, var(--wd-primary) 15%, transparent);
+  color: var(--wd-primary);
+}

package/src/layout/styles/footer.css

@@ -0,0 +1,108 @@
+/* writedocs.json's `footer.columns`/`socials` - see SiteFooter.astro (only
+   rendered at all when one of those has content) and footerSchema/
+   `socials` in lib/config.ts. Sits below .wd-shell, same max-width/
+   centering convention as .wd-topbar-inner/.wd-shell so its content lines
+   up with the rest of the page. */
+.wd-footer {
+  border-top: 1px solid var(--wd-border);
+  /* Explicit opaque background - previously unset (transparent, just
+     showing <body>'s own flat color through it, which looked identical
+     to having one). Now load-bearing: theme.background's own color/image
+     paints on <body> itself, and this is what keeps that from showing
+     through the footer. */
+  background: var(--wd-background);
+  /* body (base.css) is now the sticky-footer flex column this sits in as
+     a plain sibling after .wd-page - flex-shrink: 0 keeps this pinned at
+     its own natural height rather than the flex column trying to
+     compress it on a page taller than one viewport (harmless in
+     practice, since body has no fixed height of its own to overflow
+     against, but explicit here to match how every other fixed-size flex
+     item in this codebase - .wd-footer-brand, .wd-footer-socials below -
+     already spells this out rather than relying on it never coming up). */
+  flex-shrink: 0;
+}
+.wd-footer-inner {
+  max-width: 1440px;
+  margin: 0 auto;
+  padding: 2.5rem 1.5rem;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 2rem;
+}
+/* Only rendered when theme.logo is set (hasLogoImage) - reuses the exact
+   same wd-logo-light/wd-logo-dark <img> pair + CSS toggle (base.css) the
+   topbar brand link and mobile menu header also use, just in a third spot.
+   flex-shrink: 0 so it keeps its own size rather than getting squeezed as
+   .wd-footer-columns (flex: 1 below) claims the row's free space. */
+.wd-footer-brand {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+.wd-footer-columns {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 2.5rem;
+  flex: 1;
+}
+.wd-footer-column-title {
+  font-size: 0.78rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--wd-text-muted);
+  margin-bottom: 0.75rem;
+}
+.wd-footer-column-links {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.55rem;
+}
+.wd-footer-column-links a {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  color: var(--wd-text-muted);
+  text-decoration: none;
+  font-size: 0.88rem;
+}
+.wd-footer-column-links a:hover {
+  color: var(--wd-text);
+}
+/* flex-shrink: 0 so a wide set of columns wraps/shrinks before this row
+   does - social icons staying a fixed size reads better than them
+   shrinking or wrapping mid-row. */
+.wd-footer-socials {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.6rem;
+  flex-shrink: 0;
+}
+.wd-footer-social-link {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: 0.4rem;
+  color: var(--wd-text-muted);
+}
+.wd-footer-social-link:hover {
+  color: var(--wd-text);
+  background: var(--wd-surface);
+}
+/* AppIcon.astro renders either a real <svg> (astro-icon, for an Iconify
+   id) or a <span> (literal text/emoji). */
+svg.wd-footer-social-icon {
+  width: 1.1rem;
+  height: 1.1rem;
+}
+span.wd-footer-social-icon {
+  font-size: 1.1rem;
+  line-height: 1;
+}

package/src/layout/styles/image-zoom.css

@@ -0,0 +1,50 @@
+/* ImageZoom.astro's own styling - the fullscreen lightbox overlay, plus
+   the cursor affordance on the content images that open it (see
+   src/scripts/image-zoom.ts, which is what actually adds the
+   .wd-zoomable class - only images that end up zoomable get the cursor,
+   never Card's own image or anything marked nozoom). */
+
+.wd-zoomable {
+  cursor: zoom-in;
+}
+.wd-zoom-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2.5rem;
+  background: rgba(15, 23, 42, 0.85);
+  cursor: zoom-out;
+}
+.wd-zoom-overlay[hidden] {
+  display: none;
+}
+.wd-zoom-image {
+  max-width: 100%;
+  max-height: 100%;
+  border-radius: 0.5rem;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5);
+  cursor: zoom-out;
+}
+.wd-zoom-close {
+  position: fixed;
+  top: 1.25rem;
+  right: 1.25rem;
+  width: 2.25rem;
+  height: 2.25rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  border-radius: 50%;
+  background: rgba(255, 255, 255, 0.12);
+  color: #fff;
+  font-size: 1.5rem;
+  line-height: 1;
+  cursor: pointer;
+}
+.wd-zoom-close:hover {
+  background: rgba(255, 255, 255, 0.22);
+}