@writedocs/generator 0.4.9 → 0.4.10

package/astro.config.mjs

@@ -26,8 +26,14 @@ import { remarkAutoHydrateSnippets } from './src/lib/mdx-auto-hydrate.js';
 import { remarkInjectBuiltinComponents } from './src/lib/mdx-inject-builtins.js';
 import { remarkTitleAnchorIds } from './src/lib/mdx-title-anchor-ids.js';
 import { remarkSubstituteVariables } from './src/lib/mdx-substitute-variables.js';
-import { remarkMintlifyTreeLists, remarkMintlifyPromptText } from './src/lib/mdx-mintlify.js';
+import {
+  remarkMintlifyTreeLists,
+  remarkMintlifyPromptText,
+  remarkMintlifyReactHooks,
+  mintlifyReactHooksPlugin,
+} from './src/lib/mdx-mintlify.js';
 import { remarkUnknownComponentFallback } from './src/lib/mdx-unknown-components.js';
+import { remarkExtractInlineReactComponents } from './src/lib/mdx-inline-react.js';
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
 import {
@@ -47,6 +53,13 @@ const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
 // does the actual cross-filesystem-safe copy into contentDir/dist as an
 // explicit final step once the build itself is done.
 const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || path.dirname(fileURLToPath(import.meta.url));
+// Where this package's dependencies are: the node_modules folder that
+// contains an installed package (<project>/node_modules/@writedocs/
+// generator -> <project>/node_modules), or packageRoot itself in a checkout,
+// whose own node_modules is inside it. Used for the dev server's file-serving
+// allow list below.
+const nodeModulesAt = packageRoot.lastIndexOf(`${path.sep}node_modules${path.sep}`);
+const dependencyRoot = nodeModulesAt === -1 ? packageRoot : packageRoot.slice(0, nodeModulesAt + `${path.sep}node_modules`.length);
 
 // Read here (rather than deferred to page-render time, where
 // loadDocsConfig() is also called from [...slug].astro) specifically so
@@ -371,6 +384,14 @@ export default defineConfig({
         // the tree when it looks for components to import.
         remarkMintlifyTreeLists,
         remarkMintlifyPromptText,
+        // An inline component that calls React hooks moves into a generated
+        // .jsx file so it runs as real React (and hydrates) - see
+        // lib/mdx-inline-react.js. Before remarkMintlifyReactHooks, which
+        // imports any hooks the page itself still calls (Mintlify
+        // pre-injects them), and before remarkAutoHydrateSnippets, which
+        // hydrates the component through its new .jsx import.
+        remarkExtractInlineReactComponents,
+        remarkMintlifyReactHooks,
         // An unknown component becomes a fragment (its children still
         // render) with a warning, instead of failing the whole build - see
         // lib/mdx-unknown-components.js. After remarkMintlifyTreeLists, so
@@ -441,10 +462,26 @@ export default defineConfig({
   // working. See src/styles/global.css for the one @import that wires
   // Tailwind's utilities in.
   vite: {
+    // The dev server only serves files under its workspace root by default.
+    // A site's own snippets live in its content directory, and inline React
+    // components moved out of pages (lib/mdx-inline-react.js) in writedocs'
+    // temp directory - both need to reach the browser to hydrate. Setting
+    // `allow` replaces Vite's default rather than adding to it, so the
+    // package's dependencies must stay reachable too: when writedocs is
+    // installed, they sit next to it in the node_modules folder that
+    // contains it (React's own hydration client included), not inside
+    // packageRoot - see dependencyRoot above.
+    server: {
+      fs: {
+        allow: [packageRoot, dependencyRoot, contentDir, writedocsTempDir(contentDir)],
+      },
+    },
     // contentTailwindSource() must come before tailwindcss(): both are
     // enforce: 'pre' transforms, which Vite runs in array order, and
     // Tailwind has to see the added @source when it compiles global.css.
-    plugins: [contentTailwindSource(), tailwindcss()],
+    // mintlifyReactHooksPlugin() does for a site's .jsx/.tsx snippets what
+    // remarkMintlifyReactHooks does for its MDX pages.
+    plugins: [contentTailwindSource(), tailwindcss(), mintlifyReactHooksPlugin(contentDir)],
     resolve: {
       alias: [
         // Lets a page's MDX write `import Foo from '/snippets/foo.mdx'`

package/bin/writedocs.js

@@ -153,6 +153,29 @@ program
     }
   });
 
+program
+  .command('convert')
+  .description("Convert another docs tool's config into writedocs.json")
+  .argument('[dir]', 'project directory (contains docs.json)', '.')
+  .option('--mintlify', "convert a Mintlify project's docs.json")
+  .option('--docs.json', 'same as --mintlify')
+  .option('--force', 'overwrite an existing writedocs.json')
+  .option('--dry-run', 'print the converted writedocs.json instead of writing it')
+  .action(async (dir, options) => {
+    // --mintlify is the only source today; the flag is still required so
+    // the command reads the same once other tools are added.
+    if (!options.mintlify && !options.docsJson) {
+      console.error('[writedocs] Say what to convert from: writedocs convert --mintlify [dir]');
+      process.exit(1);
+    }
+    const { runConvert } = await import('../src/cli/convert.js');
+    await runConvert({
+      contentDir: path.resolve(process.cwd(), dir),
+      force: Boolean(options.force),
+      dryRun: Boolean(options.dryRun),
+    });
+  });
+
 program
   .command('init')
   .description('Scaffold a writedocs.json and starter docs/ folder')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/convert.js

@@ -0,0 +1,82 @@
+// `writedocs convert --mintlify [dir]` - turns a Mintlify project's
+// docs.json into writedocs.json, in the same folder, then checks the pages
+// the same way `writedocs validate` does. The conversion itself is
+// lib/mintlify-convert.js; this file is the CLI around it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadMintlifyConfig, convertMintlifyConfig, formatNotes } from '../lib/mintlify-convert.js';
+import { validateDocsConfig, formatValidationIssuesDetailed } from '../lib/config-schema.js';
+import { checkContent, formatContentIssues } from '../lib/content-check.js';
+
+export async function runConvert({ contentDir, force = false, dryRun = false }) {
+  const docsJsonPath = path.join(contentDir, 'docs.json');
+  if (!fs.existsSync(docsJsonPath)) {
+    const legacy = path.join(contentDir, 'mint.json');
+    if (fs.existsSync(legacy)) {
+      console.error(
+        `[writedocs] Found mint.json, Mintlify's older config format. Run \`npx mint upgrade\` in ${contentDir} to turn it into docs.json, then run this again.`
+      );
+    } else {
+      console.error(`[writedocs] No docs.json found in ${contentDir}.`);
+    }
+    process.exit(1);
+  }
+  const outPath = path.join(contentDir, 'writedocs.json');
+  if (!dryRun && !force && fs.existsSync(outPath)) {
+    console.error(`[writedocs] ${outPath} already exists. Pass --force to overwrite it, or --dry-run to only see the result.`);
+    process.exit(1);
+  }
+
+  let docs;
+  try {
+    docs = loadMintlifyConfig(docsJsonPath);
+  } catch (err) {
+    console.error(`[writedocs] Couldn't read ${docsJsonPath}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const { config, notes } = convertMintlifyConfig(docs);
+  const text = `${JSON.stringify(config, null, 2)}\n`;
+
+  // The result must pass writedocs' own schema - if it doesn't, that's a
+  // converter bug, and writing it would only hand the author a broken file.
+  const result = validateDocsConfig(text);
+  if (!result.ok) {
+    console.error('[writedocs] The converted writedocs.json is not valid - this is a bug in the converter, please report it:\n');
+    console.error(formatValidationIssuesDetailed(result.issues));
+    console.error(`\n${text}`);
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    console.log(text);
+  } else {
+    fs.writeFileSync(outPath, text);
+    console.log(`[writedocs] Converted ${path.basename(docsJsonPath)} -> ${outPath}`);
+  }
+
+  if (notes.length) {
+    console.log(`\n[writedocs] ${notes.length} thing${notes.length === 1 ? '' : 's'} couldn't be carried over as-is:\n`);
+    console.log(formatNotes(notes));
+  }
+
+  // The pages, checked against the converted config - what's left to fix
+  // before the first build.
+  const content = await checkContent(contentDir, text);
+  if (content.errors.length) {
+    console.log(`\n[writedocs] ${content.errors.length} error${content.errors.length === 1 ? '' : 's'} in the pages - the build would fail on these:\n`);
+    console.log(formatContentIssues(content.errors));
+  }
+  if (content.warnings.length) {
+    console.log(`\n[writedocs] ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} in the pages:\n`);
+    console.log(formatContentIssues(content.warnings));
+  }
+  console.log(
+    `\n[writedocs] Checked ${content.pages} page${content.pages === 1 ? '' : 's'}: ${content.errors.length} error${content.errors.length === 1 ? '' : 's'}, ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'}.`
+  );
+  if (!config.domain) {
+    console.log(
+      '[writedocs] Next: set "domain" in writedocs.json to your site\'s URL - it turns on sitemap.xml and absolute links for social previews. (Mintlify sets this in its dashboard, not docs.json.)'
+    );
+  }
+}

package/src/cli/generate-api-pages.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import SwaggerParser from '@apidevtools/swagger-parser';
 import matter from 'gray-matter';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+import { parseOpenApiRef, openApiOperationKey, specDirName } from '../lib/openapi-ref.js';
+import { findAllPages } from '../lib/pages.js';
 
 const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 
@@ -99,10 +101,17 @@ function scanDirForOverrides(dir, relBase, overrides) {
     }
     if (!/\.mdx?$/i.test(entry.name)) continue;
     const raw = fs.readFileSync(full, 'utf-8');
-    const { data } = matter(raw);
+    let data;
+    try {
+      ({ data } = matter(raw));
+    } catch {
+      continue; // invalid frontmatter - `writedocs validate` and the build report it
+    }
     if (typeof data.openapi !== 'string') continue;
     const fileId = rel.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
-    overrides.set(data.openapi.trim().replace(/\s+/g, ' '), fileId);
+    // Keyed by "METHOD /path" whichever form the page wrote - Mintlify's
+    // "spec.json METHOD /path" included (see lib/openapi-ref.js).
+    overrides.set(openApiOperationKey(data.openapi) ?? data.openapi.trim().replace(/\s+/g, ' '), fileId);
   }
 }
 
@@ -337,7 +346,6 @@ export async function generateApiPages({ contentDir }) {
   rmrf(openapiOutDir);
 
   const groups = collectOpenApiGroups(config.navigation);
-  if (groups.length === 0) return;
 
   const seenPaths = new Map(); // normalized path -> owning group's label
   for (const group of groups) {
@@ -356,4 +364,49 @@ export async function generateApiPages({ contentDir }) {
   for (const group of groups) {
     await generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides });
   }
+
+  await parsePageSpecs({ contentDir, openapiOutDir, groupSpecs: groups.map((g) => path.resolve(contentDir, g.openapi.src)) });
+}
+
+/** Mintlify's page-level form, `openapi: "/spec.json METHOD /path"`: the
+ *  page names its spec itself instead of belonging to an openapi group in
+ *  writedocs.json. Every such spec (that no group already parsed) is parsed
+ *  here and its operations written under openapi/_pages/<spec>/operations/,
+ *  where findOperationFile() (lib/openapi-render.ts) looks for them. No
+ *  pages are generated - the pages that name the spec are the pages. A
+ *  spec that's missing or doesn't parse is a warning, not a build failure:
+ *  its pages show the playground's own "no operation found" notice. */
+async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs }) {
+  const specs = new Set();
+  for (const rel of findAllPages(contentDir)) {
+    let data;
+    try {
+      ({ data } = matter(fs.readFileSync(path.join(contentDir, rel), 'utf-8')));
+    } catch {
+      continue;
+    }
+    const ref = parseOpenApiRef(data?.openapi);
+    if (ref?.spec) specs.add(ref.spec);
+  }
+  for (const spec of specs) {
+    const specPath = path.resolve(contentDir, spec);
+    if (groupSpecs.includes(specPath)) continue;
+    if (!fs.existsSync(specPath)) {
+      console.warn(`[writedocs] Pages name the OpenAPI spec "${spec}", which doesn't exist - their API playground shows a notice instead.`);
+      continue;
+    }
+    let operations;
+    try {
+      operations = buildOperations(await SwaggerParser.dereference(specPath));
+    } catch (err) {
+      console.warn(`[writedocs] Couldn't parse the OpenAPI spec "${spec}" that pages name: ${err.message}`);
+      continue;
+    }
+    const outDir = path.join(openapiOutDir, '_pages', specDirName(spec), 'operations');
+    fs.mkdirSync(outDir, { recursive: true });
+    for (const operation of operations) {
+      fs.writeFileSync(path.join(outDir, operationFileName(operation.method, operation.path)), JSON.stringify(operation, null, 2));
+    }
+    console.log(`[writedocs] Parsed OpenAPI spec "${spec}" for the pages that name it (${operations.length} operations)`);
+  }
 }

package/src/components/Accordion.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 import AppIcon from "./AppIcon.astro";
 
 interface Props {
@@ -32,7 +33,7 @@ function slugify(value: string): string {
 const titleId = _titleId ?? slugify(title);
 ---
 
-<details class="wd-accordion" open={defaultOpen}>
+<details class:list={["wd-accordion", extraClasses(Astro.props)]} open={defaultOpen}>
   <summary>
     <span class="wd-accordion-heading">
       {icon && <AppIcon icon={icon} class="wd-accordion-icon" />}

package/src/components/AccordionGroup.astro

@@ -1,4 +1,7 @@
-<div class="wd-accordion-group">
+---
+import { extraClasses } from './class-names';
+---
+<div class:list={["wd-accordion-group", extraClasses(Astro.props)]}>
   <slot />
 </div>
 <style is:global>

package/src/components/ApiPlayground.astro

@@ -12,6 +12,7 @@ import {
   findOperationFile,
   type OpenApiOperation,
 } from '../lib/openapi-render';
+import { parseOpenApiRef } from '../lib/openapi-ref.js';
 
 interface Props {
   operation: string; // "METHOD /path", matching a page's `openapi` frontmatter
@@ -19,8 +20,11 @@ interface Props {
 }
 const { operation, contentDir } = Astro.props as Props;
 
-const [method = '', urlPath = ''] = operation.trim().split(/\s+/, 2);
-const opFile = findOperationFile(contentDir, method, urlPath);
+// "METHOD /path", or Mintlify's "spec.json METHOD /path" - see lib/openapi-ref.js.
+const ref = parseOpenApiRef(operation);
+const method = ref?.method ?? '';
+const urlPath = ref?.path ?? '';
+const opFile = ref ? findOperationFile(contentDir, method, urlPath, ref.spec) : null;
 const op: OpenApiOperation | null = opFile ? JSON.parse(fs.readFileSync(opFile, 'utf-8')) : null;
 
 const pathParams = op?.parameters.filter((p) => p.in === 'path') ?? [];

package/src/components/ApiReferencePanel.astro

@@ -15,6 +15,7 @@ import {
   findOperationFile,
   type OpenApiOperation,
 } from '../lib/openapi-render';
+import { parseOpenApiRef } from '../lib/openapi-ref.js';
 import { loadDocsConfig, resolveCodeblockTheme } from '../lib/config';
 import ApiLangSelect from './ApiLangSelect.astro';
 
@@ -64,8 +65,11 @@ const SNIPPET_THEMES = resolveCodeblockTheme(docsConfig);
 // writedocs' CORS proxy - see PROXY_BASE_URL in the <script> below.
 const proxyEnabled = docsConfig.api.proxy;
 
-const [method = '', urlPath = ''] = operation.trim().split(/\s+/, 2);
-const opFile = findOperationFile(contentDir, method, urlPath);
+// "METHOD /path", or Mintlify's "spec.json METHOD /path" - see lib/openapi-ref.js.
+const ref = parseOpenApiRef(operation);
+const method = ref?.method ?? '';
+const urlPath = ref?.path ?? '';
+const opFile = ref ? findOperationFile(contentDir, method, urlPath, ref.spec) : null;
 const op: OpenApiOperation | null = opFile ? JSON.parse(fs.readFileSync(opFile, 'utf-8')) : null;
 
 // ApiPlayground.astro (rendered in the article column) already shows a

package/src/components/Badge.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // A small inline label - status indicators, version tags, "Beta"/"New"
 // markers - modeled on Mintlify's own Badge
 // (https://www.mintlify.com/docs/components/badge). Renders as an
@@ -42,6 +43,7 @@ const shapeClass = shape === 'pill' ? 'pill' : 'rounded';
     `wd-badge-${shapeClass}`,
     stroke && 'wd-badge-stroke',
     disabled && 'wd-badge-disabled',
+    extraClasses(Astro.props),
   ]}
 >
   {icon && <AppIcon icon={icon} class="wd-badge-icon" />}<slot />

package/src/components/Callout.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // See src/components/{Note,Tip,Warning,Danger,Info,Check}.astro - one thin
 // wrapper per `type` below, each just `<Callout type="x">` under the
 // hood, so a page can write either `<Callout type="info">` or the
@@ -51,7 +52,7 @@ function slugify(value: string): string {
 const titleId = title ? (_titleId ?? slugify(title)) : undefined;
 ---
 
-<div class:list={["wd-callout", `wd-callout-${type}`, { "wd-callout-titled": Boolean(title) }]} style={accentStyle}>
+<div class:list={["wd-callout", `wd-callout-${type}`, { "wd-callout-titled": Boolean(title) }, extraClasses(Astro.props)]} style={accentStyle}>
   <AppIcon icon={icon ?? icons[type]} class="wd-callout-icon" />
   <div class="wd-callout-content">
     {

package/src/components/Card.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 import AppIcon from './AppIcon.astro';
 
 // Three visual variants, chosen by which optional prop is set - never more
@@ -42,7 +43,7 @@ const KNOWN_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
 const methodLower = method?.toLowerCase();
 const methodClass = methodLower && KNOWN_METHODS.includes(methodLower) ? methodLower : 'other';
 ---
-<Tag class:list={['wd-card', { 'wd-card-horizontal': horizontal, 'wd-card-has-arrow': arrow && href }]} href={href}>
+<Tag class:list={['wd-card', { 'wd-card-horizontal': horizontal, 'wd-card-has-arrow': arrow && href }, extraClasses(Astro.props)]} href={href}>
   {img && <img src={img} alt="" class="wd-card-image" />}
   {!img && <AppIcon icon={icon} class="wd-card-icon" style={iconStyle} />}
   <div class="wd-card-text">

package/src/components/CardGroup.astro

@@ -1,10 +1,11 @@
 ---
+import { extraClasses } from './class-names';
 interface Props {
   cols?: number;
 }
 const { cols = 2 } = Astro.props as Props;
 ---
-<div class="wd-card-group" style={`--wd-cols: ${cols}`}>
+<div class:list={["wd-card-group", extraClasses(Astro.props)]} style={`--wd-cols: ${cols}`}>
   <slot />
 </div>
 <style>

package/src/components/Check.astro

@@ -10,4 +10,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="check" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="check" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/CodeBlock.astro

@@ -0,0 +1,94 @@
+---
+// Mintlify's <CodeBlock> - a code block from props instead of a ``` fence,
+// for code a page builds up in a component. Renders through the same Shiki
+// setup and the same writedocs:code-block transformer as a fenced block
+// (see astro.config.mjs's markdown.shikiConfig), so title, icon, line
+// numbers, wrap, copy button, expandable, highlight and focus all look and
+// behave the same.
+//
+// The code is the component's children (or a `code` prop). Mintlify's
+// `highlight`/`focus` are stringified arrays ("[1,3,4]"); ranges like
+// "1-3" work too.
+import { Code } from 'astro:components';
+import { extraClasses } from './class-names';
+import {
+  transformerMetaHighlight,
+  transformerMetaWordHighlight,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+  transformerNotationFocus,
+  transformerNotationDiff,
+  transformerNotationErrorLevel,
+} from '@shikijs/transformers';
+import { codeBlockTransformer } from '../lib/shiki-code-block.js';
+import { loadDocsConfig, resolveCodeblockTheme } from '../lib/config';
+
+interface Props {
+  language?: string;
+  filename?: string;
+  icon?: string;
+  lines?: boolean;
+  wrap?: boolean;
+  nocopy?: boolean;
+  expandable?: boolean;
+  highlight?: string | number[];
+  focus?: string | number[];
+  code?: string;
+}
+const { language = 'text', filename, icon, lines, wrap, nocopy, expandable, highlight, focus, code: codeProp } = Astro.props as Props;
+
+// Slot content arrives as rendered HTML text - undo its entity escaping.
+function unescape(html: string): string {
+  return html
+    .replace(/<[^>]+>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+const code = (codeProp ?? unescape(await Astro.slots.render('default'))).replace(/^\n+|\s+$/g, '');
+
+const ranges = (value: string | number[] | undefined) =>
+  value === undefined ? '' : (Array.isArray(value) ? value.join(',') : String(value).replace(/[\[\]\s]/g, ''));
+const quoted = (value: string) => `"${value.replace(/"/g, "'")}"`;
+const meta = [
+  filename ? `title=${quoted(filename)}` : '',
+  icon ? `icon=${quoted(icon)}` : '',
+  lines ? 'lines' : '',
+  wrap ? 'wrap' : '',
+  nocopy ? 'nocopy' : '',
+  expandable ? 'expandable' : '',
+  ranges(highlight) ? `highlight={${ranges(highlight)}}` : '',
+  ranges(focus) ? `focus={${ranges(focus)}}` : '',
+]
+  .filter(Boolean)
+  .join(' ');
+
+const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+const themes = resolveCodeblockTheme(loadDocsConfig(contentDir));
+const transformers = [
+  transformerMetaHighlight(),
+  transformerMetaWordHighlight(),
+  transformerNotationHighlight(),
+  transformerNotationWordHighlight(),
+  transformerNotationFocus(),
+  transformerNotationDiff(),
+  transformerNotationErrorLevel(),
+  codeBlockTransformer(),
+];
+const extras = extraClasses(Astro.props);
+---
+{
+  // The block's own root (.wd-code-block) is built by the Shiki transformer,
+  // so `className`/`class` goes on a wrapper around it - only when given, so
+  // a plain CodeBlock renders exactly like a fenced block.
+  extras.length > 0 ? (
+    <div class:list={extras}>
+      <Code code={code} lang={language as any} meta={meta} themes={themes} transformers={transformers} />
+    </div>
+  ) : (
+    <Code code={code} lang={language as any} meta={meta} themes={themes} transformers={transformers} />
+  )
+}

package/src/components/CodeGroup.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // `dropdown` is only ever passed down from RequestExample/
 // ResponseExample.astro today (CodeGroup itself is never used with it
 // directly in any fixture/doc) - kept as a real prop rather than a
@@ -9,7 +10,7 @@ interface Props {
 }
 const { dropdown = false } = Astro.props as Props;
 ---
-<div class="wd-codegroup" data-dropdown={dropdown ? "true" : undefined}>
+<div class:list={["wd-codegroup", extraClasses(Astro.props)]} data-dropdown={dropdown ? "true" : undefined}>
   <slot />
 </div>
 <script>

package/src/components/Color.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Color> - a palette of <Color.Item> swatches. `variant`:
 //   compact (default) - one grid of swatches.
 //   table             - <Color.Row title="..."> rows, each a titled line of
@@ -10,7 +11,7 @@ interface Props {
 }
 const { variant = 'compact' } = Astro.props as Props;
 ---
-<div class:list={['wd-color', `wd-color-${variant}`]}><slot /></div>
+<div class:list={['wd-color', `wd-color-${variant}`, extraClasses(Astro.props)]}><slot /></div>
 <script>
   // Click (or Enter/Space) on a swatch copies the value currently shown -
   // for a light/dark pair, the one matching the site's theme right now.

package/src/components/ColorItem.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Color.Item name="..." value="..."> - one swatch. `value` is
 // any CSS color, or { light, dark } for a theme-aware pair: the swatch and
 // the value text switch with the site's theme toggle ([data-theme] on
@@ -15,7 +16,7 @@ const themed = typeof value === 'object' && value !== null && light !== dark;
 const style = light ? `--wd-swatch-light: ${light}; --wd-swatch-dark: ${dark ?? light}` : undefined;
 ---
 <div
-  class="wd-color-item"
+  class:list={['wd-color-item', extraClasses(Astro.props)]}
   data-light={light}
   data-dark={dark}
   role={light ? 'button' : undefined}

package/src/components/ColorRow.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Color.Row title="..."> - one titled row inside
 // <Color variant="table">. `title` takes inline Markdown.
 import { inlineMarkdown } from '../lib/inline-markdown.js';
@@ -7,7 +8,7 @@ interface Props {
 }
 const { title } = Astro.props as Props;
 ---
-<div class="wd-color-row">
+<div class:list={['wd-color-row', extraClasses(Astro.props)]}>
   <div class="wd-color-row-title" set:html={inlineMarkdown(title ?? '')} />
   <div class="wd-color-row-items"><slot /></div>
 </div>

package/src/components/Column.astro

@@ -0,0 +1,19 @@
+---
+import { extraClasses } from './class-names';
+// Mintlify's <Column> - one cell of a <Columns> grid, for arbitrary content
+// (text, a code block) side by side rather than Cards. Just a grid item:
+// <Columns>/CardGroup.astro lays its children out, this only keeps the
+// cell's content together and trims the outer margins of what's inside.
+---
+<div class:list={['wd-column', extraClasses(Astro.props)]}><slot /></div>
+<style>
+  .wd-column {
+    min-width: 0;
+  }
+  .wd-column > :global(:first-child) {
+    margin-top: 0;
+  }
+  .wd-column > :global(:last-child) {
+    margin-bottom: 0;
+  }
+</style>

package/src/components/Columns.astro

@@ -8,4 +8,4 @@ interface Props {
 }
 const { cols } = Astro.props as Props;
 ---
-<CardGroup cols={cols}><slot /></CardGroup>
+<CardGroup cols={cols} class={Astro.props.class} className={Astro.props.className}><slot /></CardGroup>

package/src/components/Danger.astro

@@ -9,4 +9,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="danger" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="danger" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/Expandable.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // The collapsible "Show/Hide properties" wrapper that pairs with
 // Parameter for nested object properties - modeled directly on
 // Mintlify's own Expandable (https://www.mintlify.com/docs/components/
@@ -25,7 +26,7 @@ interface Props {
 const { title = "properties", defaultOpen = true } = Astro.props as Props;
 ---
 
-<details class="wd-expandable" open={defaultOpen}>
+<details class:list={["wd-expandable", extraClasses(Astro.props)]} open={defaultOpen}>
   <summary>
     <svg class="wd-expandable-chevron" width="11" height="11" viewBox="0 0 10 10" aria-hidden="true">
       <path

package/src/components/Frame.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // A generic "put a rounded, bordered card around this" wrapper -
 // deliberately different from Image (a specific <img> with its own
 // src/srcDark/size handling): Frame wraps *arbitrary* slot content - a
@@ -21,7 +22,7 @@ interface Props {
 const { caption, hint } = Astro.props as Props;
 ---
 
-<figure class="wd-frame">
+<figure class:list={["wd-frame", extraClasses(Astro.props)]}>
   {hint && <p class="wd-frame-hint">{hint}</p>}
   <div class="wd-frame-content">
     <slot />