@writedocs/generator 0.1.0

package/src/lib/mdx-auto-hydrate.js

@@ -0,0 +1,70 @@
+import { visit } from 'unist-util-visit';
+
+const CLIENT_ATTR_PREFIX = 'client:';
+const REACT_SNIPPET_EXTENSION = /\.(jsx|tsx)$/i;
+
+/**
+ * A remark plugin (registered via `mdx({ remarkPlugins: [...] })` in
+ * astro.config.mjs) that auto-adds `client:load` to every JSX usage of a
+ * component imported from a `.jsx`/`.tsx` file, unless that usage already
+ * has its own `client:*` attribute.
+ *
+ * Why this exists: Astro only ships a framework component's JS (and
+ * hydrates it in the browser) when the JSX using it carries an explicit
+ * `client:*` directive - with none, it still server-renders fine, but
+ * stays inert (no event handlers ever attach). That's the right default
+ * for Astro's own `.astro` components generally, but it means every React
+ * snippet with a hook would silently do nothing unless whoever *used* the
+ * snippet - not whoever *wrote* it - remembered to add `client:load` (or
+ * `client:visible`/`client:idle`) at each call site. Requiring every
+ * import site to know and repeat an Astro-specific detail isn't
+ * reasonable for a snippet meant to be dropped in and just work - so this
+ * makes `client:load` automatic, and an explicit `client:*` attribute (for
+ * a different hydration strategy - `client:visible`, `client:idle`,
+ * `client:only`) still works exactly as before, since this only adds the
+ * attribute when none is already present.
+ *
+ * Only affects components imported from `.jsx`/`.tsx` - `.astro` and
+ * `.mdx` imports (snippets or otherwise) are untouched, since Astro/MDX
+ * components have no hydration model to opt into in the first place;
+ * adding `client:*` to one is a compiler error, not a no-op.
+ */
+export function remarkAutoHydrateSnippets() {
+  return (tree) => {
+    const reactLocalNames = new Set();
+
+    visit(tree, 'mdxjsEsm', (node) => {
+      const body = node.data?.estree?.body;
+      if (!body) return;
+      for (const stmt of body) {
+        if (stmt.type !== 'ImportDeclaration') continue;
+        if (typeof stmt.source?.value !== 'string') continue;
+        if (!REACT_SNIPPET_EXTENSION.test(stmt.source.value)) continue;
+        for (const specifier of stmt.specifiers) {
+          // Default (`import Foo from '...'`) and named
+          // (`import { Foo } from '...'`) imports both bind a local JSX-
+          // usable identifier. A namespace import (`import * as Foo`)
+          // isn't used as a JSX tag by itself (`<Foo.Bar />` wouldn't
+          // match this node's `name` anyway - see the mdxJsxFlowElement/
+          // mdxJsxTextElement visit below), so it's left alone.
+          if (specifier.type === 'ImportDefaultSpecifier' || specifier.type === 'ImportSpecifier') {
+            reactLocalNames.add(specifier.local.name);
+          }
+        }
+      }
+    });
+
+    if (reactLocalNames.size === 0) return;
+
+    visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+      if (!node.name || !reactLocalNames.has(node.name)) return;
+      const attributes = node.attributes ?? [];
+      const hasClientDirective = attributes.some(
+        (attr) => attr.type === 'mdxJsxAttribute' && typeof attr.name === 'string' && attr.name.startsWith(CLIENT_ATTR_PREFIX)
+      );
+      if (hasClientDirective) return;
+      attributes.push({ type: 'mdxJsxAttribute', name: 'client:load', value: null });
+      node.attributes = attributes;
+    });
+  };
+}

package/src/lib/mdx-inject-builtins.js

@@ -0,0 +1,87 @@
+import { visit } from 'unist-util-visit';
+import { parse as acornParse } from 'acorn';
+
+// The exact same set [...slug].astro passes as the `components` prop to
+// every page's own <Content components={components} /> call (see
+// src/components/index.ts, the barrel this imports from) - kept as one
+// literal list rather than importing that map here, since this runs inside
+// astro.config.mjs's markdown pipeline, a different module graph than
+// [...slug].astro's own.
+const BUILTIN_COMPONENT_NAMES = [
+  'Callout',
+  'Note',
+  'Info',
+  'Tip',
+  'Warning',
+  'Danger',
+  'Card',
+  'CardGroup',
+  'Tabs',
+  'Tab',
+  'CodeGroup',
+  'Accordion',
+  'AccordionGroup',
+  'Steps',
+  'Step',
+  'Hint',
+  'Image',
+  'Frame',
+  'Video',
+  'Parameter',
+  'Expandable',
+  'Searchbar',
+  'Badge',
+  'Icon',
+  'RequestExample',
+  'ResponseExample',
+];
+
+const PACKAGE_SPECIFIER = 'writedocs/components';
+
+/**
+ * A remark plugin that auto-imports any of Writedocs' built-in components
+ * (`Callout`, `Card`, ...) a `.mdx` file uses but never itself imported -
+ * from `writedocs/components` (see src/components/index.ts) - so a snippet
+ * (see docs/dev/docs/snippets.mdx) gets the exact same zero-import
+ * experience a page under docs/ already has via [...slug].astro's own
+ * `components` prop. Runs on every `.mdx` file, pages included - harmless
+ * there since a page's own `<Callout>` usage already resolves correctly via
+ * that prop; the injected import just gives it an equally-correct direct
+ * binding instead, and doesn't touch the page's *own* file on disk (this
+ * only ever mutates the in-memory AST used for rendering, not the source
+ * the "Copy page" .md route serves - see context-menu.mdx).
+ *
+ * Respects an explicit import: if a file already imports its own `Callout`
+ * (a custom one, or re-exporting the built-in on purpose), that name is
+ * left alone rather than double-imported or overridden.
+ */
+export function remarkInjectBuiltinComponents() {
+  return (tree) => {
+    const locallyBound = new Set();
+    visit(tree, 'mdxjsEsm', (node) => {
+      const body = node.data?.estree?.body;
+      if (!body) return;
+      for (const stmt of body) {
+        if (stmt.type !== 'ImportDeclaration') continue;
+        for (const specifier of stmt.specifiers) {
+          if (specifier.local?.name) locallyBound.add(specifier.local.name);
+        }
+      }
+    });
+
+    const needed = new Set();
+    visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+      if (!node.name) return;
+      if (BUILTIN_COMPONENT_NAMES.includes(node.name) && !locallyBound.has(node.name)) {
+        needed.add(node.name);
+      }
+    });
+
+    if (needed.size === 0) return;
+
+    const names = [...needed].sort();
+    const source = `import { ${names.join(', ')} } from '${PACKAGE_SPECIFIER}';\n`;
+    const estree = acornParse(source, { ecmaVersion: 'latest', sourceType: 'module' });
+    tree.children.unshift({ type: 'mdxjsEsm', value: source, data: { estree } });
+  };
+}

package/src/lib/mdx-substitute-variables.js

@@ -0,0 +1,66 @@
+import { visit } from 'unist-util-visit';
+
+// Matches `[[key]]` - alphanumerics, dots, dashes, underscores in the key,
+// with optional whitespace padding (`[[ key ]]` also matches). Kept
+// deliberately simple/text-only: this is prose substitution, not an
+// expression language, so there's no support for defaults, nesting, or
+// anything beyond "look this key up in writedocs.json's `variables` map".
+//
+// Double square brackets, not double curly braces (`{{key}}`, the more
+// familiar templating convention from Handlebars/Mintlify-alikes) -
+// deliberately. MDX reserves single curly braces for embedded JS
+// expressions (`{jsExpression}`), and micromark-extension-mdx-expression
+// tokenizes `{...}` at *parse* time, before any remark plugin (this one
+// included) ever sees the file as an AST. `{{productName}}` in an .mdx
+// file parses as one MDX expression container whose content is the JS
+// object literal `{productName}` (shorthand for `{ productName:
+// productName }`), not as literal text at all - by the time this plugin
+// runs, there's no `text` node containing `{{productName}}` left to find,
+// and the page throws `ReferenceError: productName is not defined` at
+// render time instead. Confirmed empirically while building this
+// feature's own fixture (`25-site-config/`) - not a hypothetical concern.
+// Square brackets carry no such special meaning in MDX/CommonMark outside
+// of the `[text](url)`/`[text][ref]` link forms, both of which require a
+// `(` or second `[...]` immediately after - `[[key]]` alone never matches
+// either, so it round-trips as plain text the same way `{{key}}` would
+// have in an ordinary (non-MDX) Markdown file.
+const PLACEHOLDER = /\[\[\s*([\w.-]+)\s*\]\]/g;
+
+/**
+ * A remark plugin that replaces `[[key]]` placeholders in a page's prose
+ * with the corresponding value from writedocs.json's `variables` map (see
+ * variables: z.record(...) on docsConfigSchema in src/lib/config.ts) -
+ * e.g. `[[productName]]` becomes `Acme` everywhere a site sets
+ * `variables: { productName: "Acme" }`.
+ *
+ * Only visits `text`-type AST nodes, deliberately - `code`/`inlineCode`
+ * nodes (fenced/inline code) are a structurally separate node type in the
+ * MDX AST, so they're never visited here and a `[[...]]` written inside a
+ * code fence is left completely untouched - the same "don't mangle code"
+ * property remarkAutoHydrateSnippets and remarkInjectBuiltinComponents get
+ * from visiting narrow node-type sets rather than working on raw source
+ * text.
+ *
+ * A placeholder with no matching key is left as literal text (`[[typo]]`
+ * stays `[[typo]]`) rather than silently becoming an empty string - an
+ * unresolved placeholder rendering visibly in the built page is a much
+ * easier bug to spot than prose that's quietly missing a word.
+ *
+ * Takes `variables` as an options argument, so this attacher has to be
+ * passed to unified/remark as a `[remarkSubstituteVariables, variables]`
+ * tuple, not pre-called - see the comment on its own usage in
+ * astro.config.mjs for why calling it directly and handing unified the
+ * resulting transformer breaks the build.
+ */
+export function remarkSubstituteVariables(variables) {
+  return (tree) => {
+    if (!variables || Object.keys(variables).length === 0) return;
+
+    visit(tree, 'text', (node) => {
+      if (!node.value.includes('[[')) return;
+      node.value = node.value.replace(PLACEHOLDER, (match, key) =>
+        Object.prototype.hasOwnProperty.call(variables, key) ? variables[key] : match
+      );
+    });
+  };
+}

package/src/lib/mdx-title-anchor-ids.js

@@ -0,0 +1,84 @@
+import { visit } from 'unist-util-visit';
+
+// Every JSX tag name that can carry a `title` prop and render a linkable
+// heading of its own - the 6 Callout variants remarkInjectBuiltinComponents
+// also auto-imports (see its own BUILTIN_COMPONENT_NAMES), plus Accordion.
+// Kept as its own literal list rather than importing that one, since this
+// only cares about the subset that actually has a `title`/anchor at all
+// (Card, Tabs, AccordionGroup, etc. don't). AccordionGroup is deliberately
+// excluded - it has no `title` of its own, just wraps Accordion children
+// that each get their own entry here independently.
+const TITLED_COMPONENT_NAMES = ['Callout', 'Note', 'Info', 'Tip', 'Warning', 'Danger', 'Accordion'];
+
+// Deliberately the same slugify Callout.astro/Accordion.astro themselves
+// fall back to (see their own comments) - kept as a literal duplicate
+// rather than a shared import, since this file runs inside
+// astro.config.mjs's markdown pipeline, a different module graph than
+// either component's own (same reasoning mdx-inject-builtins.js gives for
+// not importing src/components/index.ts).
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * A remark plugin that assigns a deduped `_titleId` attribute to every
+ * <Callout title="...">/<Note title="...">/<Accordion title="...">/etc.
+ * element on a page, mirroring the -2/-3 suffixing behavior Astro's own
+ * heading-id step (github-slugger, upstream in the pipeline) already gives
+ * duplicate headings - so two of these elements with the same title text
+ * get two distinct, independently-linkable ids instead of silently
+ * colliding on the same #slug (confirmed as a real bug: the Components
+ * page has two callouts both titled "Two ways to write this").
+ *
+ * One shared `seen` map across every tag name in TITLED_COMPONENT_NAMES,
+ * not one per tag - a Callout titled "Configuration" and an Accordion
+ * titled "Configuration" later on the same page are still two different
+ * elements racing for the same #configuration slug, so they need to be
+ * deduped against each other too, not just against their own tag name.
+ *
+ * Has to happen here, not inside Callout.astro/Accordion.astro
+ * themselves - neither one ever sees more than *one* of its own
+ * invocations at a time; it has no visibility into whether some earlier
+ * element on the same page already produced the same slug. Walking the
+ * whole page's MDX AST in one pass, in document order, is the only
+ * vantage point that can dedupe correctly - the exact same reason
+ * github-slugger itself runs once per document rather than being
+ * reimplemented per-heading.
+ *
+ * Only handles a literal string `title="..."` - mdast-util-mdx-jsx gives a
+ * plain JS string for that form's attribute value, vs. an
+ * mdxJsxAttributeValueExpression node for a dynamic `title={expr}`. Every
+ * real usage in this codebase passes a plain string; a dynamic one is left
+ * alone and falls back to that component's own un-deduped slugify(title) -
+ * same behavior as before this plugin existed.
+ *
+ * Scoped per MDX *file*, not per rendered page - a snippet imported into a
+ * page (see docs/dev/docs/snippets.mdx) is its own independently-compiled
+ * MDX module with its own AST, so a title duplicated between a page and a
+ * snippet it imports won't be caught here. Acceptable for the same reason
+ * remarkInjectBuiltinComponents' own per-file scope is: there's no single
+ * shared AST spanning both by the time either one's transform runs.
+ */
+export function remarkTitleAnchorIds() {
+  return (tree) => {
+    const seen = new Map();
+    visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+      if (!node.name || !TITLED_COMPONENT_NAMES.includes(node.name)) return;
+      const titleAttr = node.attributes?.find(
+        (attr) => attr.type === 'mdxJsxAttribute' && attr.name === 'title'
+      );
+      if (!titleAttr || typeof titleAttr.value !== 'string') return;
+
+      const base = slugify(titleAttr.value);
+      if (!base) return;
+      const priorCount = seen.get(base) ?? 0;
+      seen.set(base, priorCount + 1);
+      const id = priorCount === 0 ? base : `${base}-${priorCount + 1}`;
+
+      node.attributes.push({ type: 'mdxJsxAttribute', name: '_titleId', value: id });
+    });
+  };
+}

package/src/lib/mermaid-rehype.js

@@ -0,0 +1,72 @@
+// Turns a ```mermaid fenced block into a plain <div class="mermaid">
+// containing its raw (un-highlighted) source text, ready for mermaid.js
+// to render into an SVG diagram client-side - see initMermaid() in
+// [...slug].astro for the render/re-render-on-theme-change side of this.
+//
+// Registered in astro.config.mjs's markdown.rehypePlugins, which Astro
+// runs *after* its own internal Shiki syntax-highlighting step (see
+// @astrojs/markdown-remark's index.js) - astro.config.mjs also sets
+// markdown.syntaxHighlight.excludeLangs: ['mermaid'], so a ```mermaid
+// block reaches this plugin completely untouched by Shiki: a plain
+// <pre><code class="language-mermaid">raw source</code></pre>, no
+// tokenization, no theme-specific inline styles to strip back out. This
+// plugin's only job is reshaping that into the flat container mermaid.js
+// expects (a single element directly containing the diagram source, not
+// nested in a <code>).
+//
+// Deliberately a hand-written recursive walk rather than pulling in
+// unist-util-visit for one simple find-and-replace - mirrors
+// shiki-code-block.js's own direct hast.children manipulation instead of
+// reaching for a visitor library for something this small.
+
+const LANGUAGE_MERMAID_RE = /\blanguage-mermaid\b/;
+
+function hasClass(properties, re) {
+  const className = properties?.className;
+  if (Array.isArray(className)) return className.some((c) => typeof c === 'string' && re.test(c));
+  if (typeof className === 'string') return re.test(className);
+  return false;
+}
+
+/** A Shiki-excluded ```mermaid block always survives as exactly
+ *  `<pre><code class="language-mermaid">...</code></pre>` (see
+ *  highlightCodeBlocks() in @astrojs/markdown-remark - it only ever
+ *  replaces the matched <code>'s parent when there's exactly one child),
+ *  so both checks together are enough to identify one unambiguously. */
+function isMermaidCodeBlock(node) {
+  if (node.type !== 'element' || node.tagName !== 'pre' || node.children.length !== 1) return false;
+  const code = node.children[0];
+  return code.type === 'element' && code.tagName === 'code' && hasClass(code.properties, LANGUAGE_MERMAID_RE);
+}
+
+function textOf(node) {
+  if (node.type === 'text') return node.value;
+  if (!node.children) return '';
+  return node.children.map(textOf).join('');
+}
+
+function walk(node) {
+  if (!node || !Array.isArray(node.children)) return;
+  node.children = node.children.map((child) => {
+    if (isMermaidCodeBlock(child)) {
+      const codeNode = child.children[0];
+      return {
+        type: 'element',
+        tagName: 'div',
+        // data-pagefind-ignore: raw mermaid syntax ("graph TD; A-->B;")
+        // makes for garbled, useless search excerpts - see the same
+        // attribute on [...slug].astro's .wd-prevnext nav.
+        properties: { className: ['mermaid'], 'data-pagefind-ignore': true },
+        children: [{ type: 'text', value: textOf(codeNode) }],
+      };
+    }
+    walk(child);
+    return child;
+  });
+}
+
+export function rehypeMermaid() {
+  return (tree) => {
+    walk(tree);
+  };
+}