@writedocs/generator 0.1.0

package/src/components/Steps.astro

@@ -0,0 +1,32 @@
+<div class="wd-steps"><slot /></div>
+<style is:global>
+  .wd-steps {
+    counter-reset: wd-step;
+    margin: 1.25rem 0;
+  }
+  .wd-step {
+    position: relative;
+    padding-left: 2.5rem;
+    padding-bottom: 1.5rem;
+    border-left: 2px solid var(--wd-border);
+    margin-left: 0.9rem;
+  }
+  .wd-step:last-child { border-color: transparent; padding-bottom: 0; }
+  .wd-step::before {
+    counter-increment: wd-step;
+    content: counter(wd-step);
+    position: absolute;
+    left: -0.95rem;
+    top: 0;
+    width: 1.8rem;
+    height: 1.8rem;
+    border-radius: 50%;
+    background: var(--wd-primary);
+    color: white;
+    font-size: 0.85rem;
+    font-weight: 600;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+</style>

package/src/components/Tab.astro

@@ -0,0 +1,9 @@
+---
+interface Props {
+  title: string;
+}
+const { title } = Astro.props as Props;
+---
+<div class="wd-tab" data-title={title}>
+  <slot />
+</div>

package/src/components/Tabs.astro

@@ -0,0 +1,52 @@
+<div class="wd-tabs">
+  <slot />
+</div>
+<script>
+  function initTabs(root: ParentNode) {
+    root.querySelectorAll<HTMLElement>('.wd-tabs').forEach((tabs) => {
+      if (tabs.dataset.wdInit) return;
+      tabs.dataset.wdInit = 'true';
+      const panels = Array.from(tabs.querySelectorAll<HTMLElement>(':scope > .wd-tab'));
+      const nav = document.createElement('div');
+      nav.className = 'wd-tabs-nav';
+      panels.forEach((panel, i) => {
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.textContent = panel.dataset.title ?? `Tab ${i + 1}`;
+        btn.className = 'wd-tabs-btn' + (i === 0 ? ' active' : '');
+        btn.addEventListener('click', () => {
+          nav.querySelectorAll('.wd-tabs-btn').forEach((b) => b.classList.remove('active'));
+          panels.forEach((p) => (p.style.display = 'none'));
+          btn.classList.add('active');
+          panel.style.display = 'block';
+        });
+        nav.appendChild(btn);
+        panel.style.display = i === 0 ? 'block' : 'none';
+      });
+      tabs.prepend(nav);
+    });
+  }
+  initTabs(document);
+  document.addEventListener('astro:page-load', () => initTabs(document));
+</script>
+<style is:global>
+  .wd-tabs-nav {
+    display: flex;
+    gap: 0.25rem;
+    border-bottom: 1px solid var(--wd-border);
+    margin-bottom: 1rem;
+  }
+  .wd-tabs-btn {
+    background: none;
+    border: none;
+    padding: 0.5rem 0.9rem;
+    cursor: pointer;
+    font-size: 0.9rem;
+    color: var(--wd-text-muted);
+    border-bottom: 2px solid transparent;
+  }
+  .wd-tabs-btn.active {
+    color: var(--wd-primary);
+    border-bottom-color: var(--wd-primary);
+  }
+</style>

package/src/components/Tip.astro

@@ -0,0 +1,12 @@
+---
+// Shorthand for <Callout type="tip">. See Callout.astro's own comment.
+import Callout from './Callout.astro';
+interface Props {
+  title?: string;
+  // See Callout.astro's own comment - set automatically by
+  // remarkCalloutAnchorIds, not meant to be passed by hand.
+  _titleId?: string;
+}
+const { title, _titleId } = Astro.props as Props;
+---
+<Callout type="tip" title={title} _titleId={_titleId}><slot /></Callout>

package/src/components/Video.astro

@@ -0,0 +1,135 @@
+---
+// Renders either a native <video> or an <iframe> embed from the same
+// `src` prop, auto-detected rather than requiring the author to pick -
+// `src="media/clip.mp4"` (a direct video file, local or remote) gets a
+// real <video controls>; `src="https://www.youtube.com/embed/..."` (or
+// Vimeo, Loom, any other embed URL with no recognizable video file
+// extension) gets an <iframe>. Same block-level, own-line, centered
+// shape as Image/Frame, and shares their exact card language (border-
+// radius, padding, box-shadow) - "same border radius as image and
+// frame" was the explicit ask this was built against.
+interface Props {
+  src: string;
+  // A raw CSS width ("500px", "80%", "40rem", ...) - named `width`
+  // here (not `size`, Image's own name for the same idea) to match
+  // this component's own requested API exactly. Same "applied to the
+  // wrapping figure, not the media element" approach Image.astro's own
+  // `size` prop uses (see its comment for the real bug that came from
+  // getting this wrong once already) - the whole component, card
+  // background included, sizes to `width`, not just the video/iframe
+  // inside it.
+  width?: string;
+  // Only meaningful for the <video> branch - ignored (not rendered as
+  // an attribute at all) for an <iframe> embed, since a YouTube/Vimeo
+  // player controls its own playback UI, autoplay policy, and looping
+  // through its own embed URL query params instead.
+  controls?: boolean;
+  autoplay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  // Alt text has no real equivalent for video - `title` is the
+  // accessible-name attribute both <video> (via a wrapping description)
+  // and <iframe> (a required attribute for a11y tooling to identify
+  // embedded content) actually use.
+  title?: string;
+  caption?: string;
+}
+const {
+  src,
+  width,
+  controls = true,
+  autoplay = false,
+  loop = false,
+  muted = false,
+  title,
+  caption,
+} = Astro.props as Props;
+const isFile = /\.(mp4|webm|ogg|ogv|mov|m4v)(\?.*)?(#.*)?$/i.test(src);
+const sizeStyle = width ? `--wd-video-size:${width}` : undefined;
+// Autoplaying video muted is a hard browser requirement, not a style
+// choice - every major browser silently blocks (or, worse, plays with
+// sound the visitor didn't ask for and then gets auto-paused
+// inconsistently) an unmuted autoplay <video>, so an author setting
+// autoplay without also remembering muted would get a broken-looking
+// embed rather than the "plays immediately" behavior they actually
+// asked for. Forcing it here means autoplay just works the one way
+// it's actually able to.
+const effectiveMuted = muted || autoplay;
+---
+
+<figure class:list={["wd-video-figure", caption && "wd-video-figure-framed"]} style={sizeStyle}>
+  {
+    isFile ? (
+      <video
+        class="wd-video"
+        src={src}
+        controls={controls}
+        autoplay={autoplay}
+        loop={loop}
+        muted={effectiveMuted}
+        playsinline
+        title={title}
+      />
+    ) : (
+      <iframe
+        class="wd-video wd-video-embed"
+        src={src}
+        title={title ?? "Embedded video"}
+        loading="lazy"
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+        allowfullscreen
+      />
+    )
+  }
+  {caption && <figcaption class="wd-video-caption">{caption}</figcaption>}
+</figure>
+<style>
+  /* Same three rules as Image.astro's own .wd-image-figure/
+     .wd-image-figure-framed/.wd-image-caption - see that file's own
+     comments for why width lives on the figure (not the media element),
+     why padding is what creates the inset-in-a-card look, and why
+     box-shadow exists alongside the border. Kept in sync on purpose -
+     both components are explicitly meant to look identical modulo
+     what's actually inside them. */
+  .wd-video-figure {
+    width: var(--wd-video-size, 100%);
+    max-width: 100%;
+    margin: 1.25rem auto;
+  }
+  .wd-video-figure-framed {
+    border: 1px solid var(--wd-border);
+    border-radius: 0.75rem;
+    background: var(--wd-surface);
+    padding: 0.5rem;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+  }
+  .wd-video {
+    display: block;
+    width: 100%;
+    height: auto;
+    border: 0;
+    border-radius: 0.75rem;
+  }
+  /* Unlike <img>/<video> (both read their own intrinsic dimensions once
+     loaded, so width: 100%; height: auto keeps them proportional on
+     their own), a bare <iframe> has no intrinsic size at all - without
+     something constraining its height it either collapses to the UA
+     default (~150px) or needs an explicit pixel height the embedding
+     author would have to compute themselves. aspect-ratio: 16 / 9 is
+     the standard embed shape (YouTube, Vimeo, Loom, ...) and needs no
+     JS/ResizeObserver trick to stay proportional as width changes -
+     it's a real, if imperfect, default for embeds that aren't actually
+     16:9 (a vertical/Shorts-style video letterboxes instead of filling
+     the frame), which there's no way to detect automatically from a
+     bare embed URL.
+     */
+  .wd-video-embed {
+    aspect-ratio: 16 / 9;
+  }
+  .wd-video-caption {
+    margin-top: 0.6rem;
+    text-align: center;
+    color: var(--wd-text-muted);
+    font-size: 0.75rem;
+  }
+</style>

package/src/components/Warning.astro

@@ -0,0 +1,12 @@
+---
+// Shorthand for <Callout type="warning">. See Callout.astro's own comment.
+import Callout from './Callout.astro';
+interface Props {
+  title?: string;
+  // See Callout.astro's own comment - set automatically by
+  // remarkCalloutAnchorIds, not meant to be passed by hand.
+  _titleId?: string;
+}
+const { title, _titleId } = Astro.props as Props;
+---
+<Callout type="warning" title={title} _titleId={_titleId}><slot /></Callout>

package/src/components/index.ts

@@ -0,0 +1,48 @@
+// Re-exports every component a page's own MDX gets for free (see the
+// `components` map passed to `<Content components={components} />` in
+// src/pages/[...slug].astro) as a stable, importable barrel - so
+// hand-authored content that *isn't* rendered through that same call site
+// can still use them without reaching into the package's internals.
+//
+// The one real consumer today is snippets (see docs/dev/docs/snippets.mdx):
+// a page's own MDX never needs this - Callout, Card, etc. are already in
+// scope there with no import at all - but an MDX *snippet*, imported and
+// rendered as `<MySnippet />` from inside that page, is its own
+// independently-compiled MDX component with its own (empty, unless passed
+// explicitly) components map, so a `<Callout>` used inside a snippet's own
+// body has nothing to resolve against without an import of its own. This
+// module is that import: `import { Callout } from 'writedocs/components'`
+// (see the `"./components"` entry in package.json's `exports` field, which
+// is what makes that bare specifier resolve at all - Node/Vite's package
+// self-reference resolution, no relative path into node_modules needed).
+//
+// Deliberately the same set passed into <Content components={...}> and no
+// more - AppIcon, ApiPlayground, ApiReferencePanel, CopyPageMenu etc. are
+// internal building blocks other components/layouts use, never meant to be
+// dropped into a page's MDX directly, so they're left out here too.
+export { default as Callout } from './Callout.astro';
+export { default as Note } from './Note.astro';
+export { default as Info } from './Info.astro';
+export { default as Tip } from './Tip.astro';
+export { default as Warning } from './Warning.astro';
+export { default as Danger } from './Danger.astro';
+export { default as Card } from './Card.astro';
+export { default as CardGroup } from './CardGroup.astro';
+export { default as Tabs } from './Tabs.astro';
+export { default as Tab } from './Tab.astro';
+export { default as CodeGroup } from './CodeGroup.astro';
+export { default as Accordion } from './Accordion.astro';
+export { default as AccordionGroup } from './AccordionGroup.astro';
+export { default as Steps } from './Steps.astro';
+export { default as Step } from './Step.astro';
+export { default as Hint } from './Hint.astro';
+export { default as Image } from './Image.astro';
+export { default as Frame } from './Frame.astro';
+export { default as Video } from './Video.astro';
+export { default as Parameter } from './Parameter.astro';
+export { default as Expandable } from './Expandable.astro';
+export { default as Searchbar } from './Searchbar.astro';
+export { default as Badge } from './Badge.astro';
+export { default as Icon } from './Icon.astro';
+export { default as RequestExample } from './RequestExample.astro';
+export { default as ResponseExample } from './ResponseExample.astro';

package/src/content.config.ts

@@ -0,0 +1,223 @@
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import type { Loader } from 'astro/loaders';
+import { z } from 'astro/zod';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { seoFieldsSchema, findAllPages } from './lib/config';
+import { writedocsTempDir } from './lib/writedocs-temp-dir.js';
+
+const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+
+// Astro's glob loader resolves `base` via `new URL(base, root)`. On Windows,
+// a raw path string like "C:\foo\docs" gets misparsed by the WHATWG URL
+// parser (the drive letter "C:" looks like a URL scheme), which breaks
+// downstream `fileURLToPath` calls. Passing an explicit file:// URL sidesteps
+// that entirely and works the same on every platform.
+//
+// Auto-generated OpenAPI stub pages (see generate-api-pages.js) live under
+// writedocsTempDir() - an OS-temp-directory location keyed off contentDir,
+// not anywhere inside the content directory itself - so they never show up
+// mixed in with a site's own hand-written pages, and writedocs never writes
+// generated files into a person's own project folder. The same location is
+// also where build-time manifests/caches live - see writedocs-temp-dir.js's
+// own doc comment. A separate collection (rather than a second base folder
+// glued onto `pages` somehow) because Astro's loader API has no supported
+// way to point one collection's glob() at two base directories sharing a
+// single store without each call's own "delete anything I didn't just see"
+// cleanup wiping out the other's entries - [...slug].astro merges both
+// collections' entries back into one list at query time instead, which
+// sidesteps that entirely.
+const generatedDocsDir = path.join(writedocsTempDir(contentDir), 'generated-docs');
+const generatedDocsBase = pathToFileURL(generatedDocsDir + path.sep);
+
+const docsSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  // Overrides the URL this page is served at, independent of where the
+  // file actually lives - writedocs.json's `pages` arrays always keep
+  // referencing the file's own path regardless. This is Astro's own
+  // glob()-loader convention (a `slug` frontmatter field becomes
+  // `entry.id` verbatim - see generateIdDefault in
+  // astro/dist/content/loaders/glob.js), not writedocs-specific
+  // behavior; declaring it here just brings it into the schema (and
+  // its docs) rather than leaving it an undocumented Astro feature.
+  // See fileIdForEntry() in lib/config.ts for how routes/links still
+  // resolve a page by its file id once this diverges from `entry.id`.
+  // Leading/trailing slashes are fine either way ("/", "/guides/x",
+  // "guides/x" and "guides/x/" all mean the same thing) - see
+  // normalizeEntryId() in lib/config.ts, which is what actually
+  // strips them before this value is ever used as a route or href.
+  slug: z.string().optional(),
+  // Marks this page as an OpenAPI operation reference: "METHOD /path"
+  // matching an operation in the owning group's OpenAPI spec, e.g.
+  // "GET /pets/{petId}" - [...slug].astro renders <ApiPlayground /> for
+  // any page with this field set, below the page's own MDX body (if
+  // any). Sites don't write this by hand for most pages; it's either
+  // set on a generated stub in the `generatedDocs` collection below (see
+  // generate-api-pages.js) or hand-authored to "eject" one specific
+  // operation into a real file (in `docs`) with custom prose - either
+  // way, the value is always exactly the same "METHOD /path" key
+  // generate-api-pages.js uses to look up the operation's full resolved
+  // schema/examples at render time.
+  openapi: z.string().optional(),
+  // Controls how much of the site's own chrome (topbar, sidebar, table of
+  // contents) wraps this page - see BaseLayout.astro/[...slug].astro for
+  // what each value actually removes:
+  //   default - the normal three-column reading layout (all chrome).
+  //   wide    - drops the table of contents; the article itself also
+  //             renders wider, for content that wants the extra room
+  //             (wide tables, side-by-side images).
+  //   frame   - drops the sidebar and table of contents, but keeps the
+  //             topbar and the article's own normal presentation
+  //             ("frame" as in: still inside the site's outer frame).
+  //   custom  - drops the sidebar and table of contents, the
+  //             auto-rendered <h1>, and prev/next nav, and skips the
+  //             article's own prose width/padding too - a blank canvas
+  //             for a hand-built landing/home page made entirely of
+  //             components - but keeps the topbar, so the page still
+  //             has site branding/nav/search/theme-toggle available.
+  //   blank   - everything 'custom' drops, plus the topbar too: no site
+  //             chrome at all, just <slot />. For a page that wants to
+  //             look nothing like the rest of the site (an auth screen,
+  //             a print-style page).
+  mode: z.enum(['default', 'wide', 'frame', 'custom', 'blank']).default('default'),
+  // Per-page meta tag overrides - same shape as writedocs.json's top-level
+  // `seo` (see seoFieldsSchema in lib/config.ts, the single source of
+  // truth for this shape). A page only needs to set the specific fields
+  // it wants to override; mergeSeo() falls back to the site-wide default
+  // for anything left unset. See BaseLayout.astro for where this and the
+  // site-wide seo actually get merged and rendered.
+  seo: seoFieldsSchema.optional(),
+});
+
+/** Wraps another loader so it's skipped entirely - no filesystem scan, no
+ *  "directory doesn't exist"/"no files found" warning - when its own base
+ *  directory doesn't exist yet. Astro requires every collection declared
+ *  in this file to have a loader, but most sites have no OpenAPI groups
+ *  at all (generate-api-pages.js only ever creates a generated-docs/
+ *  directory under writedocsTempDir() when at least one exists), so without this
+ *  the `generatedDocs` collection below would print a spurious warning on
+ *  every single build/dev run for the common case of a site with no
+ *  OpenAPI pages. */
+function skipIfMissing(inner: Loader): Loader {
+  return {
+    name: inner.name,
+    load: async (context) => {
+      if (!fs.existsSync(generatedDocsBase)) return;
+      return inner.load(context);
+    },
+  };
+}
+
+const generatedDocs = defineCollection({
+  loader: skipIfMissing(glob({ pattern: '**/*.{md,mdx}', base: generatedDocsBase })),
+  schema: docsSchema,
+});
+
+// Every hand-written page in the project, wherever it lives - see
+// findAllPages() in lib/config.ts for the exact discovery rule (any
+// .md/.mdx file with a frontmatter block, the usual build/dependency
+// directories excluded - docs/ has no special status, it's scanned like
+// any other folder). A single collection covering the whole content
+// directory works here (unlike generatedDocs, which needs its own
+// separate collection - see that const's own comment) because there's
+// only one base to worry about: the content root itself.
+//
+// The literal file list (rather than a `**/*.{md,mdx}` pattern) is what
+// actually implements the frontmatter-based filter: glob()'s `pattern`
+// option takes glob patterns, not a predicate function, so the predicate
+// has to run first, here, to produce the list glob() then just matches
+// literally. Astro's own default id computation, scoped to this same
+// content-root base, is what gives a page under docs/ its "docs/..."
+// file id and a page at the root its bare file id - see
+// fileIdForEntry()'s own comment in lib/config.ts for the one place that
+// id computation needs to be independently recovered (once a page's
+// frontmatter `slug` has overridden `entry.id` itself).
+const contentRootBase = pathToFileURL(contentDir + path.sep);
+
+/** Wraps astro's own glob() loader so pages are re-discovered live during
+ *  `astro dev`, not just once when this module first evaluates.
+ *
+ *  The naive approach - `glob({ pattern: findAllPages(contentDir), base })`,
+ *  computed once at module load, as this used to be - works fine for the
+ *  *first* load, but astro's glob loader's own dev-mode watcher only ever
+ *  matches entries against whatever literal pattern list it was constructed
+ *  with (see matchesGlob() in astro's glob.js, called from its `watcher.on(
+ *  'add', ...)` handler): a file created after that list was computed can
+ *  never match it, so it silently never becomes a page until the dev server
+ *  is restarted and this module re-evaluates findAllPages() from scratch.
+ *  That's the exact bug this wrapper fixes.
+ *
+ *  A plain wildcard pattern (`**\/*.{md,mdx}`) doesn't work as a substitute,
+ *  either: whether a given .md/.mdx file counts as a page at all depends on
+ *  its *content* (does it have a frontmatter block? - see findAllPages()'s
+ *  own doc comment, this is what lets e.g. snippets/ partials with no
+ *  frontmatter coexist in the content dir without becoming pages
+ *  themselves), not just its path, and glob()'s `pattern` option only does
+ *  path matching - it can't express that filter. Something has to re-run
+ *  findAllPages() itself, content and all, whenever the file set changes.
+ *
+ *  So: this re-invokes astro's own glob() loader - reusing all of its real
+ *  parsing/rendering/digest-based caching logic rather than reimplementing
+ *  any of that - with a freshly recomputed literal file list every time
+ *  something relevant changes on disk, instead of once. The inner loader's
+ *  own watcher wiring is deliberately skipped each time (`watcher` is
+ *  stripped from the context passed to it) - this loader keeps exactly one
+ *  watcher subscription of its own instead, covering every case uniformly
+ *  (a new page file appearing, one being deleted, frontmatter being added
+ *  to or removed from an existing file, ordinary content edits) rather than
+ *  relying on the inner loader's add/change/unlink handlers, which - as
+ *  above - are only ever bound to whatever the pattern looked like at the
+ *  moment they were registered. */
+function livePages(dir: string, base: URL): Loader {
+  return {
+    name: 'writedocs-live-pages',
+    load: async (context) => {
+      const { watcher, store, logger } = context;
+
+      async function resync() {
+        const files = findAllPages(dir);
+        if (files.length === 0) {
+          // Mirrors the old skipIfEmpty() wrapper: skip calling the inner
+          // loader entirely (rather than passing it an empty/impossible
+          // pattern) so astro doesn't print its own "no files found"
+          // warning for a freshly-scaffolded project with no content yet -
+          // but still clear out any previously-synced entries, in case a
+          // page's last file was just deleted mid dev-session rather than
+          // this being the initial load of an empty project.
+          for (const id of store.keys()) store.delete(id);
+          return;
+        }
+        await glob({ pattern: files, base }).load({ ...context, watcher: undefined });
+      }
+
+      await resync();
+      if (!watcher) return; // no watcher outside `astro dev` (e.g. `astro build`)
+
+      watcher.add(fileURLToPath(base));
+      let pending: ReturnType<typeof setTimeout> | undefined;
+      const scheduleResync = (changedPath: string) => {
+        if (!/\.mdx?$/i.test(changedPath)) return;
+        clearTimeout(pending);
+        // Debounced: an editor's "save" can fire several fs events in
+        // quick succession (e.g. atomic-write = unlink+add), and adding
+        // several files at once shouldn't trigger a resync per file.
+        pending = setTimeout(() => {
+          resync().catch((err) => logger.error(`Failed to reload pages: ${err.message}`));
+        }, 100);
+      };
+      watcher.on('add', scheduleResync);
+      watcher.on('unlink', scheduleResync);
+      watcher.on('change', scheduleResync);
+    },
+  };
+}
+
+const pages = defineCollection({
+  loader: livePages(contentDir, contentRootBase),
+  schema: docsSchema,
+});
+
+export const collections = { pages, generatedDocs };