doxla 0.3.8 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # doxla
 
-Improve documentation discoverability within repos. Doxla discovers all `.md` files in your repository, builds a beautiful docs viewer, and deploys it to GitHub Pages.
+Improve documentation discoverability within repos. Doxla discovers all `.md` and `.mdx` files in your repository, builds a beautiful docs viewer, and deploys it to GitHub Pages.
 
 ## Why?
 
@@ -8,7 +8,7 @@ Documentation is most valuable when it lives next to the code it describes — b
 
 Meanwhile, AI coding assistants (Claude Code, Copilot, Cursor) work with what's in the repository. Docs in Notion or Google Docs are invisible to them. In-repo markdown is context they can read and act on.
 
-Doxla bridges the gap: keep your docs as `.md` files in your repo (where both humans and AI agents can find them), and Doxla turns them into a readable, searchable site.
+Doxla bridges the gap: keep your docs as `.md` or `.mdx` files in your repo (where both humans and AI agents can find them), and Doxla turns them into a readable, searchable site.
 
 Read the full rationale: [Why Doxla?](RATIONALE.md)
 
@@ -36,11 +36,12 @@ This creates a GitHub Actions workflow that builds and deploys your docs on ever
 npx doxla build
 ```
 
-This discovers all markdown files, builds a static docs site, and outputs it to `doxla-dist/`.
+This discovers all markdown and MDX files, builds a static docs site, and outputs it to `doxla-dist/`.
 
 ## Features
 
-- Automatic markdown file discovery (respects `.gitignore`-style patterns)
+- Automatic `.md` and `.mdx` file discovery (respects `.gitignore`-style patterns)
+- MDX support with built-in components (`<Callout>`) and JSX expressions
 - Beautiful React-based docs viewer with sidebar navigation
 - Full-text search across all documents
 - Syntax highlighting for code blocks
@@ -64,7 +65,7 @@ Creates `.github/workflows/doxla.yml` for automatic GitHub Pages deployment.
 
 ## How It Works
 
-1. **Discover** - Scans your repo for `.md` files (excluding `node_modules`, `.git`, etc.)
+1. **Discover** - Scans your repo for `.md` and `.mdx` files (excluding `node_modules`, `.git`, etc.)
 2. **Manifest** - Reads each file, extracts titles, and generates a JSON manifest
 3. **Build** - Copies the built-in React app template, injects the manifest, and runs `vite build`
 4. **Output** - Produces a static site ready for any hosting

package/dist/cli/index.js

@@ -86,14 +86,14 @@ var IGNORE_PATTERNS = [
   "**/coverage/**"
 ];
 async function discoverMarkdownFiles(rootDir) {
-  const files = await fg("**/*.md", {
+  const files = await fg("**/*.{md,mdx}", {
     cwd: rootDir,
     ignore: IGNORE_PATTERNS,
     onlyFiles: true
   });
   return files.sort((a, b) => {
-    const aIsReadme = a.toLowerCase() === "readme.md";
-    const bIsReadme = b.toLowerCase() === "readme.md";
+    const aIsReadme = /^readme\.mdx?$/i.test(a);
+    const bIsReadme = /^readme\.mdx?$/i.test(b);
     if (aIsReadme && !bIsReadme) return -1;
     if (!aIsReadme && bIsReadme) return 1;
     return a.localeCompare(b);
@@ -108,7 +108,8 @@ function extractTitle(content, filePath) {
   if (match) {
     return match[1].trim();
   }
-  const name = basename(filePath, ".md");
+  const ext = filePath.endsWith(".mdx") ? ".mdx" : ".md";
+  const name = basename(filePath, ext);
   if (name.toLowerCase() === "readme") {
     const dir = dirname(filePath);
     if (dir === ".") return "README";
@@ -117,7 +118,7 @@ function extractTitle(content, filePath) {
   return name.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 function createSlug(filePath) {
-  return filePath.replace(/\.md$/i, "").replace(/\\/g, "/").toLowerCase().replace(/[^a-z0-9/.-]/g, "-");
+  return filePath.replace(/\.mdx?$/i, "").replace(/\\/g, "/").toLowerCase().replace(/[^a-z0-9/.-]/g, "-");
 }
 async function generateManifest(rootDir, files) {
   const docs = await Promise.all(

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/cli/index.ts","../../src/cli/commands/init.ts","../../src/cli/templates/doxla-workflow.ts","../../src/cli/commands/build.ts","../../src/cli/lib/discover.ts","../../src/cli/lib/manifest.ts","../../src/cli/lib/build-app.ts","../../src/cli/lib/template.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { initCommand } from \"./commands/init.js\";\nimport { buildCommand } from \"./commands/build.js\";\n\nconst program = new Command();\n\nprogram\n  .name(\"doxla\")\n  .description(\"Improve documentation discoverability within repos\")\n  .version(\"0.1.0\");\n\nprogram\n  .command(\"init\")\n  .description(\"Set up GitHub Actions workflow for Doxla docs deployment\")\n  .action(initCommand);\n\nprogram\n  .command(\"build\")\n  .description(\"Discover markdown files and build the docs viewer\")\n  .option(\"-o, --output <dir>\", \"Output directory\", \"doxla-dist\")\n  .option(\"-r, --root <dir>\", \"Root directory to scan for markdown files\", \".\")\n  .option(\"--base-path <path>\", \"Base path for GitHub Pages deployment\", \"/\")\n  .action(buildCommand);\n\nprogram.parse();\n","import { mkdir, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { existsSync } from \"node:fs\";\nimport chalk from \"chalk\";\nimport { workflowTemplate } from \"../templates/doxla-workflow.js\";\n\nexport async function initCommand() {\n  const workflowDir = join(process.cwd(), \".github\", \"workflows\");\n  const workflowPath = join(workflowDir, \"doxla.yml\");\n\n  if (existsSync(workflowPath)) {\n    console.log(\n      chalk.yellow(\"⚠ Workflow file already exists at .github/workflows/doxla.yml\")\n    );\n    console.log(chalk.yellow(\"  Overwriting with latest template...\"));\n  }\n\n  await mkdir(workflowDir, { recursive: true });\n  await writeFile(workflowPath, workflowTemplate, \"utf-8\");\n\n  console.log(chalk.green(\"✓ Created .github/workflows/doxla.yml\"));\n  console.log();\n  console.log(\"Next steps:\");\n  console.log(\n    `  1. Enable GitHub Pages in your repo settings (Settings → Pages → Source: ${chalk.bold(\"GitHub Actions\")})`\n  );\n  console.log(\"  2. Commit and push the workflow file\");\n  console.log(\n    \"  3. Your docs will be built and deployed on every push to main\"\n  );\n}\n","export const workflowTemplate = `name: Deploy Doxla Docs\n\non:\n  push:\n    branches: [main]\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: \"pages\"\n  cancel-in-progress: false\n\njobs:\n  build-and-deploy:\n    runs-on: ubuntu-latest\n    environment:\n      name: github-pages\n      url: \\${{ steps.deployment.outputs.page_url }}\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n      - run: npx doxla@latest build --base-path \"/\\${{ github.event.repository.name }}\"\n      - uses: actions/upload-pages-artifact@v3\n        with:\n          path: ./doxla-dist\n      - id: deployment\n        uses: actions/deploy-pages@v4\n`;\n","import { resolve } from \"node:path\";\nimport chalk from \"chalk\";\nimport ora from \"ora\";\nimport { discoverMarkdownFiles } from \"../lib/discover.js\";\nimport { generateManifest } from \"../lib/manifest.js\";\nimport { buildApp } from \"../lib/build-app.js\";\n\ninterface BuildOptions {\n  output: string;\n  root: string;\n  basePath: string;\n}\n\nexport async function buildCommand(options: BuildOptions) {\n  const rootDir = resolve(options.root);\n  const outputDir = resolve(options.output);\n  const basePath = options.basePath;\n\n  console.log(chalk.bold(\"doxla build\"));\n  console.log();\n\n  // Step 1: Discover markdown files\n  const discoverSpinner = ora(\"Discovering markdown files...\").start();\n  const files = await discoverMarkdownFiles(rootDir);\n\n  if (files.length === 0) {\n    discoverSpinner.fail(\"No markdown files found\");\n    process.exit(1);\n  }\n\n  discoverSpinner.succeed(`Found ${files.length} markdown file${files.length === 1 ? \"\" : \"s\"}`);\n\n  // Step 2: Generate manifest\n  const manifestSpinner = ora(\"Generating manifest...\").start();\n  const manifest = await generateManifest(rootDir, files);\n  manifestSpinner.succeed(\"Manifest generated\");\n\n  // Step 3: Build docs viewer\n  const buildSpinner = ora(\"Building docs viewer...\").start();\n  try {\n    await buildApp(manifest, { output: outputDir, basePath });\n    buildSpinner.succeed(\"Docs viewer built\");\n  } catch (error) {\n    buildSpinner.fail(\"Build failed\");\n    console.error(chalk.red((error as Error).message));\n    process.exit(1);\n  }\n\n  console.log();\n  console.log(chalk.green(`✓ Output written to ${options.output}/`));\n}\n","import fg from \"fast-glob\";\n\nconst IGNORE_PATTERNS = [\n  \"**/node_modules/**\",\n  \"**/.git/**\",\n  \"**/dist/**\",\n  \"**/build/**\",\n  \"**/doxla-dist/**\",\n  \"**/.next/**\",\n  \"**/coverage/**\",\n];\n\nexport async function discoverMarkdownFiles(rootDir: string): Promise<string[]> {\n  const files = await fg(\"**/*.md\", {\n    cwd: rootDir,\n    ignore: IGNORE_PATTERNS,\n    onlyFiles: true,\n  });\n\n  // Sort: README.md first, then alphabetical\n  return files.sort((a, b) => {\n    const aIsReadme = a.toLowerCase() === \"readme.md\";\n    const bIsReadme = b.toLowerCase() === \"readme.md\";\n    if (aIsReadme && !bIsReadme) return -1;\n    if (!aIsReadme && bIsReadme) return 1;\n    return a.localeCompare(b);\n  });\n}\n","import { readFile } from \"node:fs/promises\";\nimport { join, basename, dirname } from \"node:path\";\nimport type { Manifest, DocFile } from \"../../app/src/types/manifest.js\";\n\nfunction extractTitle(content: string, filePath: string): string {\n  // Try to extract from first # heading\n  const match = content.match(/^#\\s+(.+)$/m);\n  if (match) {\n    return match[1].trim();\n  }\n\n  // Fallback to filename without extension\n  const name = basename(filePath, \".md\");\n  if (name.toLowerCase() === \"readme\") {\n    const dir = dirname(filePath);\n    if (dir === \".\") return \"README\";\n    return `${dir} - README`;\n  }\n  return name.replace(/[-_]/g, \" \").replace(/\\b\\w/g, (c) => c.toUpperCase());\n}\n\nfunction createSlug(filePath: string): string {\n  return filePath\n    .replace(/\\.md$/i, \"\")\n    .replace(/\\\\/g, \"/\")\n    .toLowerCase()\n    .replace(/[^a-z0-9/.-]/g, \"-\");\n}\n\nexport async function generateManifest(\n  rootDir: string,\n  files: string[]\n): Promise<Manifest> {\n  const docs: DocFile[] = await Promise.all(\n    files.map(async (filePath) => {\n      const fullPath = join(rootDir, filePath);\n      const content = await readFile(fullPath, \"utf-8\");\n      return {\n        slug: createSlug(filePath),\n        path: filePath,\n        title: extractTitle(content, filePath),\n        content,\n      };\n    })\n  );\n\n  const repoName = basename(rootDir);\n\n  return {\n    repoName,\n    generatedAt: new Date().toISOString(),\n    totalDocs: docs.length,\n    docs,\n  };\n}\n","import { cp, writeFile, rm, mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { tmpdir } from \"node:os\";\nimport { execSync } from \"node:child_process\";\nimport { randomBytes } from \"node:crypto\";\nimport type { Manifest } from \"../../app/src/types/manifest.js\";\nimport { getTemplatePath } from \"./template.js\";\n\ninterface BuildOptions {\n  output: string;\n  basePath: string;\n}\n\nexport async function buildApp(\n  manifest: Manifest,\n  options: BuildOptions\n): Promise<void> {\n  const templateDir = getTemplatePath();\n  const tempDir = join(\n    tmpdir(),\n    `doxla-build-${randomBytes(6).toString(\"hex\")}`\n  );\n\n  try {\n    // Copy template to temp dir\n    await cp(templateDir, tempDir, { recursive: true });\n\n    // Write manifest.json into the app's src directory\n    await writeFile(\n      join(tempDir, \"src\", \"manifest.json\"),\n      JSON.stringify(manifest, null, 2),\n      \"utf-8\"\n    );\n\n    // Install dependencies\n    execSync(\"npm install --no-audit --no-fund\", {\n      cwd: tempDir,\n      stdio: \"pipe\",\n    });\n\n    // Build with Vite, passing base path as env var\n    execSync(\"npx vite build\", {\n      cwd: tempDir,\n      stdio: \"pipe\",\n      env: { ...process.env, VITE_BASE_PATH: options.basePath },\n    });\n\n    // Copy output\n    await rm(options.output, { recursive: true, force: true });\n    await mkdir(options.output, { recursive: true });\n    await cp(join(tempDir, \"dist\"), options.output, { recursive: true });\n  } finally {\n    // Clean up temp dir\n    await rm(tempDir, { recursive: true, force: true }).catch(() => {});\n  }\n}\n","import { fileURLToPath } from \"node:url\";\nimport { dirname, resolve } from \"node:path\";\nimport { existsSync } from \"node:fs\";\n\nexport function getTemplatePath(): string {\n  const __filename = fileURLToPath(import.meta.url);\n  let dir = dirname(__filename);\n\n  // Walk up from the current file location until we find src/app\n  // Works both from source (src/cli/lib/) and built (dist/cli/)\n  for (let i = 0; i < 5; i++) {\n    const candidate = resolve(dir, \"src\", \"app\");\n    if (existsSync(resolve(candidate, \"package.json\"))) {\n      return candidate;\n    }\n    dir = dirname(dir);\n  }\n\n  // Fallback: assume built location dist/cli/ -> ../../src/app\n  const fallback = resolve(dirname(__filename), \"..\", \"..\", \"src\", \"app\");\n  return fallback;\n}\n"],"mappings":";;;AAAA,SAAS,eAAe;;;ACAxB,SAAS,OAAO,iBAAiB;AACjC,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAC3B,OAAO,WAAW;;;ACHX,IAAM,mBAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ADMhC,eAAsB,cAAc;AAClC,QAAM,cAAc,KAAK,QAAQ,IAAI,GAAG,WAAW,WAAW;AAC9D,QAAM,eAAe,KAAK,aAAa,WAAW;AAElD,MAAI,WAAW,YAAY,GAAG;AAC5B,YAAQ;AAAA,MACN,MAAM,OAAO,oEAA+D;AAAA,IAC9E;AACA,YAAQ,IAAI,MAAM,OAAO,uCAAuC,CAAC;AAAA,EACnE;AAEA,QAAM,MAAM,aAAa,EAAE,WAAW,KAAK,CAAC;AAC5C,QAAM,UAAU,cAAc,kBAAkB,OAAO;AAEvD,UAAQ,IAAI,MAAM,MAAM,4CAAuC,CAAC;AAChE,UAAQ,IAAI;AACZ,UAAQ,IAAI,aAAa;AACzB,UAAQ;AAAA,IACN,wFAA8E,MAAM,KAAK,gBAAgB,CAAC;AAAA,EAC5G;AACA,UAAQ,IAAI,wCAAwC;AACpD,UAAQ;AAAA,IACN;AAAA,EACF;AACF;;;AE9BA,SAAS,WAAAA,gBAAe;AACxB,OAAOC,YAAW;AAClB,OAAO,SAAS;;;ACFhB,OAAO,QAAQ;AAEf,IAAM,kBAAkB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,eAAsB,sBAAsB,SAAoC;AAC9E,QAAM,QAAQ,MAAM,GAAG,WAAW;AAAA,IAChC,KAAK;AAAA,IACL,QAAQ;AAAA,IACR,WAAW;AAAA,EACb,CAAC;AAGD,SAAO,MAAM,KAAK,CAAC,GAAG,MAAM;AAC1B,UAAM,YAAY,EAAE,YAAY,MAAM;AACtC,UAAM,YAAY,EAAE,YAAY,MAAM;AACtC,QAAI,aAAa,CAAC,UAAW,QAAO;AACpC,QAAI,CAAC,aAAa,UAAW,QAAO;AACpC,WAAO,EAAE,cAAc,CAAC;AAAA,EAC1B,CAAC;AACH;;;AC3BA,SAAS,gBAAgB;AACzB,SAAS,QAAAC,OAAM,UAAU,eAAe;AAGxC,SAAS,aAAa,SAAiB,UAA0B;AAE/D,QAAM,QAAQ,QAAQ,MAAM,aAAa;AACzC,MAAI,OAAO;AACT,WAAO,MAAM,CAAC,EAAE,KAAK;AAAA,EACvB;AAGA,QAAM,OAAO,SAAS,UAAU,KAAK;AACrC,MAAI,KAAK,YAAY,MAAM,UAAU;AACnC,UAAM,MAAM,QAAQ,QAAQ;AAC5B,QAAI,QAAQ,IAAK,QAAO;AACxB,WAAO,GAAG,GAAG;AAAA,EACf;AACA,SAAO,KAAK,QAAQ,SAAS,GAAG,EAAE,QAAQ,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC;AAC3E;AAEA,SAAS,WAAW,UAA0B;AAC5C,SAAO,SACJ,QAAQ,UAAU,EAAE,EACpB,QAAQ,OAAO,GAAG,EAClB,YAAY,EACZ,QAAQ,iBAAiB,GAAG;AACjC;AAEA,eAAsB,iBACpB,SACA,OACmB;AACnB,QAAM,OAAkB,MAAM,QAAQ;AAAA,IACpC,MAAM,IAAI,OAAO,aAAa;AAC5B,YAAM,WAAWA,MAAK,SAAS,QAAQ;AACvC,YAAM,UAAU,MAAM,SAAS,UAAU,OAAO;AAChD,aAAO;AAAA,QACL,MAAM,WAAW,QAAQ;AAAA,QACzB,MAAM;AAAA,QACN,OAAO,aAAa,SAAS,QAAQ;AAAA,QACrC;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AAEA,QAAM,WAAW,SAAS,OAAO;AAEjC,SAAO;AAAA,IACL;AAAA,IACA,cAAa,oBAAI,KAAK,GAAE,YAAY;AAAA,IACpC,WAAW,KAAK;AAAA,IAChB;AAAA,EACF;AACF;;;ACtDA,SAAS,IAAI,aAAAC,YAAW,IAAI,SAAAC,cAAa;AACzC,SAAS,QAAAC,aAAY;AACrB,SAAS,cAAc;AACvB,SAAS,gBAAgB;AACzB,SAAS,mBAAmB;;;ACJ5B,SAAS,qBAAqB;AAC9B,SAAS,WAAAC,UAAS,eAAe;AACjC,SAAS,cAAAC,mBAAkB;AAEpB,SAAS,kBAA0B;AACxC,QAAM,aAAa,cAAc,YAAY,GAAG;AAChD,MAAI,MAAMD,SAAQ,UAAU;AAI5B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,YAAY,QAAQ,KAAK,OAAO,KAAK;AAC3C,QAAIC,YAAW,QAAQ,WAAW,cAAc,CAAC,GAAG;AAClD,aAAO;AAAA,IACT;AACA,UAAMD,SAAQ,GAAG;AAAA,EACnB;AAGA,QAAM,WAAW,QAAQA,SAAQ,UAAU,GAAG,MAAM,MAAM,OAAO,KAAK;AACtE,SAAO;AACT;;;ADRA,eAAsB,SACpB,UACA,SACe;AACf,QAAM,cAAc,gBAAgB;AACpC,QAAM,UAAUE;AAAA,IACd,OAAO;AAAA,IACP,eAAe,YAAY,CAAC,EAAE,SAAS,KAAK,CAAC;AAAA,EAC/C;AAEA,MAAI;AAEF,UAAM,GAAG,aAAa,SAAS,EAAE,WAAW,KAAK,CAAC;AAGlD,UAAMC;AAAA,MACJD,MAAK,SAAS,OAAO,eAAe;AAAA,MACpC,KAAK,UAAU,UAAU,MAAM,CAAC;AAAA,MAChC;AAAA,IACF;AAGA,aAAS,oCAAoC;AAAA,MAC3C,KAAK;AAAA,MACL,OAAO;AAAA,IACT,CAAC;AAGD,aAAS,kBAAkB;AAAA,MACzB,KAAK;AAAA,MACL,OAAO;AAAA,MACP,KAAK,EAAE,GAAG,QAAQ,KAAK,gBAAgB,QAAQ,SAAS;AAAA,IAC1D,CAAC;AAGD,UAAM,GAAG,QAAQ,QAAQ,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AACzD,UAAME,OAAM,QAAQ,QAAQ,EAAE,WAAW,KAAK,CAAC;AAC/C,UAAM,GAAGF,MAAK,SAAS,MAAM,GAAG,QAAQ,QAAQ,EAAE,WAAW,KAAK,CAAC;AAAA,EACrE,UAAE;AAEA,UAAM,GAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACpE;AACF;;;AH1CA,eAAsB,aAAa,SAAuB;AACxD,QAAM,UAAUG,SAAQ,QAAQ,IAAI;AACpC,QAAM,YAAYA,SAAQ,QAAQ,MAAM;AACxC,QAAM,WAAW,QAAQ;AAEzB,UAAQ,IAAIC,OAAM,KAAK,aAAa,CAAC;AACrC,UAAQ,IAAI;AAGZ,QAAM,kBAAkB,IAAI,+BAA+B,EAAE,MAAM;AACnE,QAAM,QAAQ,MAAM,sBAAsB,OAAO;AAEjD,MAAI,MAAM,WAAW,GAAG;AACtB,oBAAgB,KAAK,yBAAyB;AAC9C,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,kBAAgB,QAAQ,SAAS,MAAM,MAAM,iBAAiB,MAAM,WAAW,IAAI,KAAK,GAAG,EAAE;AAG7F,QAAM,kBAAkB,IAAI,wBAAwB,EAAE,MAAM;AAC5D,QAAM,WAAW,MAAM,iBAAiB,SAAS,KAAK;AACtD,kBAAgB,QAAQ,oBAAoB;AAG5C,QAAM,eAAe,IAAI,yBAAyB,EAAE,MAAM;AAC1D,MAAI;AACF,UAAM,SAAS,UAAU,EAAE,QAAQ,WAAW,SAAS,CAAC;AACxD,iBAAa,QAAQ,mBAAmB;AAAA,EAC1C,SAAS,OAAO;AACd,iBAAa,KAAK,cAAc;AAChC,YAAQ,MAAMA,OAAM,IAAK,MAAgB,OAAO,CAAC;AACjD,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,UAAQ,IAAI;AACZ,UAAQ,IAAIA,OAAM,MAAM,4BAAuB,QAAQ,MAAM,GAAG,CAAC;AACnE;;;AH9CA,IAAM,UAAU,IAAI,QAAQ;AAE5B,QACG,KAAK,OAAO,EACZ,YAAY,oDAAoD,EAChE,QAAQ,OAAO;AAElB,QACG,QAAQ,MAAM,EACd,YAAY,0DAA0D,EACtE,OAAO,WAAW;AAErB,QACG,QAAQ,OAAO,EACf,YAAY,mDAAmD,EAC/D,OAAO,sBAAsB,oBAAoB,YAAY,EAC7D,OAAO,oBAAoB,6CAA6C,GAAG,EAC3E,OAAO,sBAAsB,yCAAyC,GAAG,EACzE,OAAO,YAAY;AAEtB,QAAQ,MAAM;","names":["resolve","chalk","join","writeFile","mkdir","join","dirname","existsSync","join","writeFile","mkdir","resolve","chalk"]}
+{"version":3,"sources":["../../src/cli/index.ts","../../src/cli/commands/init.ts","../../src/cli/templates/doxla-workflow.ts","../../src/cli/commands/build.ts","../../src/cli/lib/discover.ts","../../src/cli/lib/manifest.ts","../../src/cli/lib/build-app.ts","../../src/cli/lib/template.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { initCommand } from \"./commands/init.js\";\nimport { buildCommand } from \"./commands/build.js\";\n\nconst program = new Command();\n\nprogram\n  .name(\"doxla\")\n  .description(\"Improve documentation discoverability within repos\")\n  .version(\"0.1.0\");\n\nprogram\n  .command(\"init\")\n  .description(\"Set up GitHub Actions workflow for Doxla docs deployment\")\n  .action(initCommand);\n\nprogram\n  .command(\"build\")\n  .description(\"Discover markdown files and build the docs viewer\")\n  .option(\"-o, --output <dir>\", \"Output directory\", \"doxla-dist\")\n  .option(\"-r, --root <dir>\", \"Root directory to scan for markdown files\", \".\")\n  .option(\"--base-path <path>\", \"Base path for GitHub Pages deployment\", \"/\")\n  .action(buildCommand);\n\nprogram.parse();\n","import { mkdir, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { existsSync } from \"node:fs\";\nimport chalk from \"chalk\";\nimport { workflowTemplate } from \"../templates/doxla-workflow.js\";\n\nexport async function initCommand() {\n  const workflowDir = join(process.cwd(), \".github\", \"workflows\");\n  const workflowPath = join(workflowDir, \"doxla.yml\");\n\n  if (existsSync(workflowPath)) {\n    console.log(\n      chalk.yellow(\"⚠ Workflow file already exists at .github/workflows/doxla.yml\")\n    );\n    console.log(chalk.yellow(\"  Overwriting with latest template...\"));\n  }\n\n  await mkdir(workflowDir, { recursive: true });\n  await writeFile(workflowPath, workflowTemplate, \"utf-8\");\n\n  console.log(chalk.green(\"✓ Created .github/workflows/doxla.yml\"));\n  console.log();\n  console.log(\"Next steps:\");\n  console.log(\n    `  1. Enable GitHub Pages in your repo settings (Settings → Pages → Source: ${chalk.bold(\"GitHub Actions\")})`\n  );\n  console.log(\"  2. Commit and push the workflow file\");\n  console.log(\n    \"  3. Your docs will be built and deployed on every push to main\"\n  );\n}\n","export const workflowTemplate = `name: Deploy Doxla Docs\n\non:\n  push:\n    branches: [main]\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: \"pages\"\n  cancel-in-progress: false\n\njobs:\n  build-and-deploy:\n    runs-on: ubuntu-latest\n    environment:\n      name: github-pages\n      url: \\${{ steps.deployment.outputs.page_url }}\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n      - run: npx doxla@latest build --base-path \"/\\${{ github.event.repository.name }}\"\n      - uses: actions/upload-pages-artifact@v3\n        with:\n          path: ./doxla-dist\n      - id: deployment\n        uses: actions/deploy-pages@v4\n`;\n","import { resolve } from \"node:path\";\nimport chalk from \"chalk\";\nimport ora from \"ora\";\nimport { discoverMarkdownFiles } from \"../lib/discover.js\";\nimport { generateManifest } from \"../lib/manifest.js\";\nimport { buildApp } from \"../lib/build-app.js\";\n\ninterface BuildOptions {\n  output: string;\n  root: string;\n  basePath: string;\n}\n\nexport async function buildCommand(options: BuildOptions) {\n  const rootDir = resolve(options.root);\n  const outputDir = resolve(options.output);\n  const basePath = options.basePath;\n\n  console.log(chalk.bold(\"doxla build\"));\n  console.log();\n\n  // Step 1: Discover markdown files\n  const discoverSpinner = ora(\"Discovering markdown files...\").start();\n  const files = await discoverMarkdownFiles(rootDir);\n\n  if (files.length === 0) {\n    discoverSpinner.fail(\"No markdown files found\");\n    process.exit(1);\n  }\n\n  discoverSpinner.succeed(`Found ${files.length} markdown file${files.length === 1 ? \"\" : \"s\"}`);\n\n  // Step 2: Generate manifest\n  const manifestSpinner = ora(\"Generating manifest...\").start();\n  const manifest = await generateManifest(rootDir, files);\n  manifestSpinner.succeed(\"Manifest generated\");\n\n  // Step 3: Build docs viewer\n  const buildSpinner = ora(\"Building docs viewer...\").start();\n  try {\n    await buildApp(manifest, { output: outputDir, basePath });\n    buildSpinner.succeed(\"Docs viewer built\");\n  } catch (error) {\n    buildSpinner.fail(\"Build failed\");\n    console.error(chalk.red((error as Error).message));\n    process.exit(1);\n  }\n\n  console.log();\n  console.log(chalk.green(`✓ Output written to ${options.output}/`));\n}\n","import fg from \"fast-glob\";\n\nconst IGNORE_PATTERNS = [\n  \"**/node_modules/**\",\n  \"**/.git/**\",\n  \"**/dist/**\",\n  \"**/build/**\",\n  \"**/doxla-dist/**\",\n  \"**/.next/**\",\n  \"**/coverage/**\",\n];\n\nexport async function discoverMarkdownFiles(rootDir: string): Promise<string[]> {\n  const files = await fg(\"**/*.{md,mdx}\", {\n    cwd: rootDir,\n    ignore: IGNORE_PATTERNS,\n    onlyFiles: true,\n  });\n\n  // Sort: README.md/README.mdx first, then alphabetical\n  return files.sort((a, b) => {\n    const aIsReadme = /^readme\\.mdx?$/i.test(a);\n    const bIsReadme = /^readme\\.mdx?$/i.test(b);\n    if (aIsReadme && !bIsReadme) return -1;\n    if (!aIsReadme && bIsReadme) return 1;\n    return a.localeCompare(b);\n  });\n}\n","import { readFile } from \"node:fs/promises\";\nimport { join, basename, dirname } from \"node:path\";\nimport type { Manifest, DocFile } from \"../../app/src/types/manifest.js\";\n\nfunction extractTitle(content: string, filePath: string): string {\n  // Try to extract from first # heading\n  const match = content.match(/^#\\s+(.+)$/m);\n  if (match) {\n    return match[1].trim();\n  }\n\n  // Fallback to filename without extension\n  const ext = filePath.endsWith(\".mdx\") ? \".mdx\" : \".md\";\n  const name = basename(filePath, ext);\n  if (name.toLowerCase() === \"readme\") {\n    const dir = dirname(filePath);\n    if (dir === \".\") return \"README\";\n    return `${dir} - README`;\n  }\n  return name.replace(/[-_]/g, \" \").replace(/\\b\\w/g, (c) => c.toUpperCase());\n}\n\nfunction createSlug(filePath: string): string {\n  return filePath\n    .replace(/\\.mdx?$/i, \"\")\n    .replace(/\\\\/g, \"/\")\n    .toLowerCase()\n    .replace(/[^a-z0-9/.-]/g, \"-\");\n}\n\nexport async function generateManifest(\n  rootDir: string,\n  files: string[]\n): Promise<Manifest> {\n  const docs: DocFile[] = await Promise.all(\n    files.map(async (filePath) => {\n      const fullPath = join(rootDir, filePath);\n      const content = await readFile(fullPath, \"utf-8\");\n      return {\n        slug: createSlug(filePath),\n        path: filePath,\n        title: extractTitle(content, filePath),\n        content,\n      };\n    })\n  );\n\n  const repoName = basename(rootDir);\n\n  return {\n    repoName,\n    generatedAt: new Date().toISOString(),\n    totalDocs: docs.length,\n    docs,\n  };\n}\n","import { cp, writeFile, rm, mkdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { tmpdir } from \"node:os\";\nimport { execSync } from \"node:child_process\";\nimport { randomBytes } from \"node:crypto\";\nimport type { Manifest } from \"../../app/src/types/manifest.js\";\nimport { getTemplatePath } from \"./template.js\";\n\ninterface BuildOptions {\n  output: string;\n  basePath: string;\n}\n\nexport async function buildApp(\n  manifest: Manifest,\n  options: BuildOptions\n): Promise<void> {\n  const templateDir = getTemplatePath();\n  const tempDir = join(\n    tmpdir(),\n    `doxla-build-${randomBytes(6).toString(\"hex\")}`\n  );\n\n  try {\n    // Copy template to temp dir\n    await cp(templateDir, tempDir, { recursive: true });\n\n    // Write manifest.json into the app's src directory\n    await writeFile(\n      join(tempDir, \"src\", \"manifest.json\"),\n      JSON.stringify(manifest, null, 2),\n      \"utf-8\"\n    );\n\n    // Install dependencies\n    execSync(\"npm install --no-audit --no-fund\", {\n      cwd: tempDir,\n      stdio: \"pipe\",\n    });\n\n    // Build with Vite, passing base path as env var\n    execSync(\"npx vite build\", {\n      cwd: tempDir,\n      stdio: \"pipe\",\n      env: { ...process.env, VITE_BASE_PATH: options.basePath },\n    });\n\n    // Copy output\n    await rm(options.output, { recursive: true, force: true });\n    await mkdir(options.output, { recursive: true });\n    await cp(join(tempDir, \"dist\"), options.output, { recursive: true });\n  } finally {\n    // Clean up temp dir\n    await rm(tempDir, { recursive: true, force: true }).catch(() => {});\n  }\n}\n","import { fileURLToPath } from \"node:url\";\nimport { dirname, resolve } from \"node:path\";\nimport { existsSync } from \"node:fs\";\n\nexport function getTemplatePath(): string {\n  const __filename = fileURLToPath(import.meta.url);\n  let dir = dirname(__filename);\n\n  // Walk up from the current file location until we find src/app\n  // Works both from source (src/cli/lib/) and built (dist/cli/)\n  for (let i = 0; i < 5; i++) {\n    const candidate = resolve(dir, \"src\", \"app\");\n    if (existsSync(resolve(candidate, \"package.json\"))) {\n      return candidate;\n    }\n    dir = dirname(dir);\n  }\n\n  // Fallback: assume built location dist/cli/ -> ../../src/app\n  const fallback = resolve(dirname(__filename), \"..\", \"..\", \"src\", \"app\");\n  return fallback;\n}\n"],"mappings":";;;AAAA,SAAS,eAAe;;;ACAxB,SAAS,OAAO,iBAAiB;AACjC,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAC3B,OAAO,WAAW;;;ACHX,IAAM,mBAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ADMhC,eAAsB,cAAc;AAClC,QAAM,cAAc,KAAK,QAAQ,IAAI,GAAG,WAAW,WAAW;AAC9D,QAAM,eAAe,KAAK,aAAa,WAAW;AAElD,MAAI,WAAW,YAAY,GAAG;AAC5B,YAAQ;AAAA,MACN,MAAM,OAAO,oEAA+D;AAAA,IAC9E;AACA,YAAQ,IAAI,MAAM,OAAO,uCAAuC,CAAC;AAAA,EACnE;AAEA,QAAM,MAAM,aAAa,EAAE,WAAW,KAAK,CAAC;AAC5C,QAAM,UAAU,cAAc,kBAAkB,OAAO;AAEvD,UAAQ,IAAI,MAAM,MAAM,4CAAuC,CAAC;AAChE,UAAQ,IAAI;AACZ,UAAQ,IAAI,aAAa;AACzB,UAAQ;AAAA,IACN,wFAA8E,MAAM,KAAK,gBAAgB,CAAC;AAAA,EAC5G;AACA,UAAQ,IAAI,wCAAwC;AACpD,UAAQ;AAAA,IACN;AAAA,EACF;AACF;;;AE9BA,SAAS,WAAAA,gBAAe;AACxB,OAAOC,YAAW;AAClB,OAAO,SAAS;;;ACFhB,OAAO,QAAQ;AAEf,IAAM,kBAAkB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,eAAsB,sBAAsB,SAAoC;AAC9E,QAAM,QAAQ,MAAM,GAAG,iBAAiB;AAAA,IACtC,KAAK;AAAA,IACL,QAAQ;AAAA,IACR,WAAW;AAAA,EACb,CAAC;AAGD,SAAO,MAAM,KAAK,CAAC,GAAG,MAAM;AAC1B,UAAM,YAAY,kBAAkB,KAAK,CAAC;AAC1C,UAAM,YAAY,kBAAkB,KAAK,CAAC;AAC1C,QAAI,aAAa,CAAC,UAAW,QAAO;AACpC,QAAI,CAAC,aAAa,UAAW,QAAO;AACpC,WAAO,EAAE,cAAc,CAAC;AAAA,EAC1B,CAAC;AACH;;;AC3BA,SAAS,gBAAgB;AACzB,SAAS,QAAAC,OAAM,UAAU,eAAe;AAGxC,SAAS,aAAa,SAAiB,UAA0B;AAE/D,QAAM,QAAQ,QAAQ,MAAM,aAAa;AACzC,MAAI,OAAO;AACT,WAAO,MAAM,CAAC,EAAE,KAAK;AAAA,EACvB;AAGA,QAAM,MAAM,SAAS,SAAS,MAAM,IAAI,SAAS;AACjD,QAAM,OAAO,SAAS,UAAU,GAAG;AACnC,MAAI,KAAK,YAAY,MAAM,UAAU;AACnC,UAAM,MAAM,QAAQ,QAAQ;AAC5B,QAAI,QAAQ,IAAK,QAAO;AACxB,WAAO,GAAG,GAAG;AAAA,EACf;AACA,SAAO,KAAK,QAAQ,SAAS,GAAG,EAAE,QAAQ,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC;AAC3E;AAEA,SAAS,WAAW,UAA0B;AAC5C,SAAO,SACJ,QAAQ,YAAY,EAAE,EACtB,QAAQ,OAAO,GAAG,EAClB,YAAY,EACZ,QAAQ,iBAAiB,GAAG;AACjC;AAEA,eAAsB,iBACpB,SACA,OACmB;AACnB,QAAM,OAAkB,MAAM,QAAQ;AAAA,IACpC,MAAM,IAAI,OAAO,aAAa;AAC5B,YAAM,WAAWA,MAAK,SAAS,QAAQ;AACvC,YAAM,UAAU,MAAM,SAAS,UAAU,OAAO;AAChD,aAAO;AAAA,QACL,MAAM,WAAW,QAAQ;AAAA,QACzB,MAAM;AAAA,QACN,OAAO,aAAa,SAAS,QAAQ;AAAA,QACrC;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AAEA,QAAM,WAAW,SAAS,OAAO;AAEjC,SAAO;AAAA,IACL;AAAA,IACA,cAAa,oBAAI,KAAK,GAAE,YAAY;AAAA,IACpC,WAAW,KAAK;AAAA,IAChB;AAAA,EACF;AACF;;;ACvDA,SAAS,IAAI,aAAAC,YAAW,IAAI,SAAAC,cAAa;AACzC,SAAS,QAAAC,aAAY;AACrB,SAAS,cAAc;AACvB,SAAS,gBAAgB;AACzB,SAAS,mBAAmB;;;ACJ5B,SAAS,qBAAqB;AAC9B,SAAS,WAAAC,UAAS,eAAe;AACjC,SAAS,cAAAC,mBAAkB;AAEpB,SAAS,kBAA0B;AACxC,QAAM,aAAa,cAAc,YAAY,GAAG;AAChD,MAAI,MAAMD,SAAQ,UAAU;AAI5B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,YAAY,QAAQ,KAAK,OAAO,KAAK;AAC3C,QAAIC,YAAW,QAAQ,WAAW,cAAc,CAAC,GAAG;AAClD,aAAO;AAAA,IACT;AACA,UAAMD,SAAQ,GAAG;AAAA,EACnB;AAGA,QAAM,WAAW,QAAQA,SAAQ,UAAU,GAAG,MAAM,MAAM,OAAO,KAAK;AACtE,SAAO;AACT;;;ADRA,eAAsB,SACpB,UACA,SACe;AACf,QAAM,cAAc,gBAAgB;AACpC,QAAM,UAAUE;AAAA,IACd,OAAO;AAAA,IACP,eAAe,YAAY,CAAC,EAAE,SAAS,KAAK,CAAC;AAAA,EAC/C;AAEA,MAAI;AAEF,UAAM,GAAG,aAAa,SAAS,EAAE,WAAW,KAAK,CAAC;AAGlD,UAAMC;AAAA,MACJD,MAAK,SAAS,OAAO,eAAe;AAAA,MACpC,KAAK,UAAU,UAAU,MAAM,CAAC;AAAA,MAChC;AAAA,IACF;AAGA,aAAS,oCAAoC;AAAA,MAC3C,KAAK;AAAA,MACL,OAAO;AAAA,IACT,CAAC;AAGD,aAAS,kBAAkB;AAAA,MACzB,KAAK;AAAA,MACL,OAAO;AAAA,MACP,KAAK,EAAE,GAAG,QAAQ,KAAK,gBAAgB,QAAQ,SAAS;AAAA,IAC1D,CAAC;AAGD,UAAM,GAAG,QAAQ,QAAQ,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AACzD,UAAME,OAAM,QAAQ,QAAQ,EAAE,WAAW,KAAK,CAAC;AAC/C,UAAM,GAAGF,MAAK,SAAS,MAAM,GAAG,QAAQ,QAAQ,EAAE,WAAW,KAAK,CAAC;AAAA,EACrE,UAAE;AAEA,UAAM,GAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACpE;AACF;;;AH1CA,eAAsB,aAAa,SAAuB;AACxD,QAAM,UAAUG,SAAQ,QAAQ,IAAI;AACpC,QAAM,YAAYA,SAAQ,QAAQ,MAAM;AACxC,QAAM,WAAW,QAAQ;AAEzB,UAAQ,IAAIC,OAAM,KAAK,aAAa,CAAC;AACrC,UAAQ,IAAI;AAGZ,QAAM,kBAAkB,IAAI,+BAA+B,EAAE,MAAM;AACnE,QAAM,QAAQ,MAAM,sBAAsB,OAAO;AAEjD,MAAI,MAAM,WAAW,GAAG;AACtB,oBAAgB,KAAK,yBAAyB;AAC9C,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,kBAAgB,QAAQ,SAAS,MAAM,MAAM,iBAAiB,MAAM,WAAW,IAAI,KAAK,GAAG,EAAE;AAG7F,QAAM,kBAAkB,IAAI,wBAAwB,EAAE,MAAM;AAC5D,QAAM,WAAW,MAAM,iBAAiB,SAAS,KAAK;AACtD,kBAAgB,QAAQ,oBAAoB;AAG5C,QAAM,eAAe,IAAI,yBAAyB,EAAE,MAAM;AAC1D,MAAI;AACF,UAAM,SAAS,UAAU,EAAE,QAAQ,WAAW,SAAS,CAAC;AACxD,iBAAa,QAAQ,mBAAmB;AAAA,EAC1C,SAAS,OAAO;AACd,iBAAa,KAAK,cAAc;AAChC,YAAQ,MAAMA,OAAM,IAAK,MAAgB,OAAO,CAAC;AACjD,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,UAAQ,IAAI;AACZ,UAAQ,IAAIA,OAAM,MAAM,4BAAuB,QAAQ,MAAM,GAAG,CAAC;AACnE;;;AH9CA,IAAM,UAAU,IAAI,QAAQ;AAE5B,QACG,KAAK,OAAO,EACZ,YAAY,oDAAoD,EAChE,QAAQ,OAAO;AAElB,QACG,QAAQ,MAAM,EACd,YAAY,0DAA0D,EACtE,OAAO,WAAW;AAErB,QACG,QAAQ,OAAO,EACf,YAAY,mDAAmD,EAC/D,OAAO,sBAAsB,oBAAoB,YAAY,EAC7D,OAAO,oBAAoB,6CAA6C,GAAG,EAC3E,OAAO,sBAAsB,yCAAyC,GAAG,EACzE,OAAO,YAAY;AAEtB,QAAQ,MAAM;","names":["resolve","chalk","join","writeFile","mkdir","join","dirname","existsSync","join","writeFile","mkdir","resolve","chalk"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxla",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Improve documentation discoverability within repos",
   "type": "module",
   "bin": {
@@ -41,6 +41,7 @@
     "ora": "^8.2.0"
   },
   "devDependencies": {
+    "@mdx-js/mdx": "^3.1.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.12.0",

package/src/app/package.json

@@ -9,6 +9,7 @@
   "dependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "@mdx-js/mdx": "^3.1.0",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.0",
     "react-syntax-highlighter": "^15.6.1",

package/src/app/src/components/DocPage.tsx

@@ -1,6 +1,7 @@
 import type { DocFile } from "../types/manifest";
 import type { Theme } from "../App";
 import { MarkdownRenderer } from "./MarkdownRenderer";
+import { MdxRenderer } from "./MdxRenderer";
 import { Badge } from "./ui/Badge";
 import { Separator } from "./ui/Separator";
 
@@ -9,8 +10,13 @@ interface DocPageProps {
   theme: Theme;
 }
 
+function isMdx(path: string): boolean {
+  return path.endsWith(".mdx");
+}
+
 export function DocPage({ doc, theme }: DocPageProps) {
   const pathParts = doc.path.split("/");
+  const mdx = isMdx(doc.path);
 
   return (
     <div>
@@ -32,12 +38,16 @@ export function DocPage({ doc, theme }: DocPageProps) {
 
       <div className="mb-4 flex items-center gap-3">
         <h1 className="text-3xl font-bold">{doc.title}</h1>
-        <Badge variant="secondary">.md</Badge>
+        <Badge variant="secondary">{mdx ? ".mdx" : ".md"}</Badge>
       </div>
 
       <Separator className="mb-6" />
 
-      <MarkdownRenderer content={doc.content} theme={theme} docPath={doc.path} />
+      {mdx ? (
+        <MdxRenderer content={doc.content} theme={theme} docPath={doc.path} />
+      ) : (
+        <MarkdownRenderer content={doc.content} theme={theme} docPath={doc.path} />
+      )}
     </div>
   );
 }

package/src/app/src/components/MarkdownRenderer.tsx

@@ -5,6 +5,7 @@ import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { oneLight, oneDark } from "react-syntax-highlighter/dist/esm/styles/prism";
 import type { Components } from "react-markdown";
 import type { Theme } from "../App";
+import { resolveDocLink } from "../lib/doc-links";
 
 interface MarkdownRendererProps {
   content: string;
@@ -12,29 +13,6 @@ interface MarkdownRendererProps {
   docPath?: string;
 }
 
-function resolveDocLink(href: string, docPath: string): string | null {
-  if (!href.match(/\.md(#.*)?$/i)) return null;
-  if (/^https?:\/\//.test(href)) return null;
-
-  const [filePart, anchor] = href.split("#");
-  const docDir = docPath.includes("/") ? docPath.replace(/\/[^/]+$/, "") : "";
-  const parts = (docDir ? `${docDir}/${filePart}` : filePart).split("/");
-
-  const resolved: string[] = [];
-  for (const part of parts) {
-    if (part === "..") resolved.pop();
-    else if (part !== ".") resolved.push(part);
-  }
-
-  const slug = resolved
-    .join("/")
-    .replace(/\.md$/i, "")
-    .toLowerCase()
-    .replace(/[^a-z0-9/.-]/g, "-");
-
-  return `#/doc/${slug}${anchor ? `#${anchor}` : ""}`;
-}
-
 export function MarkdownRenderer({ content, theme, docPath }: MarkdownRendererProps) {
   const syntaxStyle = theme === "dark" ? oneDark : oneLight;
 

package/src/app/src/components/MdxRenderer.tsx

@@ -0,0 +1,124 @@
+import { useState, useEffect, useMemo } from "react";
+import type { ComponentType, ReactNode } from "react";
+import * as jsxRuntime from "react/jsx-runtime";
+import { evaluate } from "@mdx-js/mdx";
+import remarkGfm from "remark-gfm";
+import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
+import { oneLight, oneDark } from "react-syntax-highlighter/dist/esm/styles/prism";
+import type { Theme } from "../App";
+import { resolveDocLink } from "../lib/doc-links";
+import { Callout } from "./mdx/Callout";
+import { MdxErrorBoundary } from "./mdx/MdxErrorBoundary";
+
+interface MdxRendererProps {
+  content: string;
+  theme: Theme;
+  docPath?: string;
+}
+
+const builtinComponents = {
+  Callout,
+};
+
+// WARNING: evaluate() executes arbitrary JavaScript from MDX content.
+// Only use with trusted content from your own repository.
+export function MdxRenderer({ content, theme, docPath }: MdxRendererProps) {
+  const [MdxContent, setMdxContent] = useState<ComponentType<{ components?: Record<string, unknown> }> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const syntaxStyle = theme === "dark" ? oneDark : oneLight;
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function compileMdx() {
+      try {
+        const { default: Content } = await evaluate(content, {
+          ...jsxRuntime,
+          remarkPlugins: [remarkGfm],
+        } as Parameters<typeof evaluate>[1]);
+
+        if (!cancelled) {
+          setMdxContent(() => Content);
+          setError(null);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError((err as Error).message);
+          setMdxContent(null);
+        }
+      }
+    }
+
+    compileMdx();
+    return () => { cancelled = true; };
+  }, [content]);
+
+  const mdxComponents = useMemo(() => ({
+    ...builtinComponents,
+    code(props: Record<string, unknown>) {
+      const { children, className, ...rest } = props;
+      const match = /language-(\w+)/.exec((className as string) || "");
+      const isInline = !match;
+
+      if (isInline) {
+        return (
+          <code
+            className="rounded bg-muted px-1.5 py-0.5 text-sm font-mono"
+            {...rest}
+          >
+            {children as ReactNode}
+          </code>
+        );
+      }
+
+      return (
+        <SyntaxHighlighter
+          style={syntaxStyle}
+          language={match[1]}
+          PreTag="div"
+          className="rounded-md text-sm"
+        >
+          {String(children).replace(/\n$/, "")}
+        </SyntaxHighlighter>
+      );
+    },
+    a(props: Record<string, unknown>) {
+      const { href, children, ...rest } = props;
+      if (href && docPath) {
+        const resolved = resolveDocLink(href as string, docPath);
+        if (resolved) {
+          return <a href={resolved} {...rest}>{children as ReactNode}</a>;
+        }
+      }
+      return <a href={href as string} {...rest}>{children as ReactNode}</a>;
+    },
+  }), [syntaxStyle, docPath]);
+
+  if (error) {
+    return (
+      <div className="rounded-md border border-red-300 bg-red-50 p-4 text-red-800 dark:border-red-800 dark:bg-red-950/30 dark:text-red-300">
+        <p className="font-semibold">MDX Error</p>
+        <pre className="mt-2 text-sm whitespace-pre-wrap">{error}</pre>
+      </div>
+    );
+  }
+
+  if (!MdxContent) {
+    return (
+      <div className="animate-pulse space-y-3">
+        <div className="h-6 w-1/3 rounded bg-muted" />
+        <div className="h-4 w-full rounded bg-muted" />
+        <div className="h-4 w-2/3 rounded bg-muted" />
+      </div>
+    );
+  }
+
+  return (
+    <div className={`prose prose-neutral max-w-none ${theme === "dark" ? "prose-invert" : ""}`}>
+      <MdxErrorBoundary>
+        <MdxContent components={mdxComponents} />
+      </MdxErrorBoundary>
+    </div>
+  );
+}

package/src/app/src/components/mdx/Callout.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import { cn } from "../../lib/utils";
+
+interface CalloutProps {
+  type?: "info" | "warning" | "danger";
+  children: ReactNode;
+}
+
+const styles = {
+  info: "border-blue-500/40 bg-blue-50 text-blue-900 dark:bg-blue-950/30 dark:text-blue-200",
+  warning: "border-yellow-500/40 bg-yellow-50 text-yellow-900 dark:bg-yellow-950/30 dark:text-yellow-200",
+  danger: "border-red-500/40 bg-red-50 text-red-900 dark:bg-red-950/30 dark:text-red-200",
+};
+
+const labels: Record<string, string> = {
+  info: "Info",
+  warning: "Warning",
+  danger: "Danger",
+};
+
+export function Callout({ type = "info", children }: CalloutProps) {
+  return (
+    <div className={cn("my-4 rounded-md border-l-4 p-4", styles[type])}>
+      <p className="mb-1 text-sm font-semibold">{labels[type]}</p>
+      <div className="text-sm [&>p]:m-0">{children}</div>
+    </div>
+  );
+}

package/src/app/src/components/mdx/MdxErrorBoundary.tsx

@@ -0,0 +1,44 @@
+import { Component } from "react";
+import type { ReactNode, ErrorInfo } from "react";
+
+interface Props {
+  children: ReactNode;
+}
+
+interface State {
+  error: string | null;
+}
+
+export class MdxErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error: error.message };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error("MDX runtime error:", error, info);
+  }
+
+  componentDidUpdate(prevProps: Props) {
+    if (prevProps.children !== this.props.children && this.state.error) {
+      this.setState({ error: null });
+    }
+  }
+
+  render() {
+    if (this.state.error) {
+      return (
+        <div className="rounded-md border border-red-300 bg-red-50 p-4 text-red-800 dark:border-red-800 dark:bg-red-950/30 dark:text-red-300">
+          <p className="font-semibold">MDX Runtime Error</p>
+          <pre className="mt-2 text-sm whitespace-pre-wrap">{this.state.error}</pre>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/src/app/src/lib/doc-links.ts

@@ -0,0 +1,28 @@
+export function resolveDocLink(href: string, docPath: string): string | null {
+  if (!href.match(/\.mdx?(#.*)?$/i)) return null;
+  if (/^https?:\/\//.test(href)) return null;
+
+  const [filePart, anchor] = href.split("#");
+  const docDir = docPath.includes("/") ? docPath.replace(/\/[^/]+$/, "") : "";
+  const parts = (docDir ? `${docDir}/${filePart}` : filePart).split("/");
+
+  const resolved: string[] = [];
+  for (const part of parts) {
+    if (part === "..") {
+      if (resolved.length > 0) resolved.pop();
+      else return null;
+    } else if (part !== ".") {
+      resolved.push(part);
+    }
+  }
+
+  const slug = resolved
+    .join("/")
+    .replace(/\.mdx?$/i, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9/.-]/g, "-");
+
+  if (!slug) return null;
+
+  return `#/doc/${slug}${anchor ? `#${anchor}` : ""}`;
+}