boltdocs 1.10.2 → 1.11.0

package/src/node/mdx.ts

@@ -1,25 +1,183 @@
-import mdxPlugin from "@mdx-js/rollup";
-import remarkGfm from "remark-gfm";
-import remarkFrontmatter from "remark-frontmatter";
-import rehypeSlug from "rehype-slug";
-import rehypePrettyCode from "rehype-pretty-code";
-import type { Plugin } from "vite";
-import crypto from "crypto";
+import mdxPlugin from '@mdx-js/rollup'
+import remarkGfm from 'remark-gfm'
+import remarkFrontmatter from 'remark-frontmatter'
+import rehypeSlug from 'rehype-slug'
+import type { Plugin } from 'vite'
+import crypto from 'crypto'
+import { visit } from 'unist-util-visit'
+import { createHighlighter } from 'shiki'
 
-import type { BoltdocsConfig } from "./config";
-import { TransformCache } from "./cache";
+import type { Highlighter } from 'shiki'
+
+import type { BoltdocsConfig } from './config'
+import { TransformCache } from './cache'
+
+let shikiHighlighter: Highlighter | null = null
+
+/**
+ * Retrieves or initializes the Shiki highlighter instance.
+ * Supports dual-theme configurations (light/dark).
+ *
+ * @param codeTheme - Theme configuration (string for single, object for dual).
+ * @returns A promise resolving to the highlighter instance.
+ */
+async function getShikiHighlighter(codeTheme: any) {
+  if (shikiHighlighter) return shikiHighlighter
+
+  const themes =
+    typeof codeTheme === 'object'
+      ? [codeTheme.light, codeTheme.dark]
+      : [codeTheme ?? 'github-dark']
+
+  // Fallbacks for standard themes
+  ;['github-light', 'github-dark'].forEach((t) => {
+    if (!themes.includes(t)) themes.push(t)
+  })
+
+  // Initialize with a core set of languages first to speed up boot
+  shikiHighlighter = await createHighlighter({
+    themes,
+    langs: [
+      'tsx',
+      'jsx',
+      'ts',
+      'js',
+      'json',
+      'md',
+      'mdx',
+      'css',
+      'html',
+      'bash',
+      'sh',
+      'yaml',
+      'yml',
+    ],
+  })
+
+  return shikiHighlighter
+}
+
+/**
+ * Custom remark plugin to highlight code in ComponentPreview components.
+ * This runs before rehype, ensuring that the 'highlightedHtml' prop is correctly
+ * attached to the MDX component as a JSX attribute.
+ *
+ * Supports both string literals and MDX expression values (template literals)
+ * for the 'code' attribute.
+ *
+ * @param config - The Boltdocs configuration
+ * @returns A remark plugin function
+ */
+export function remarkShiki(config?: BoltdocsConfig) {
+  return async (tree: any) => {
+    const codeTheme = config?.themeConfig?.codeTheme ?? {
+      light: 'github-light',
+      dark: 'github-dark',
+    }
+    const highlighter = await getShikiHighlighter(codeTheme)
+
+    visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node: any) => {
+      if (node.name !== 'ComponentPreview') return
+
+      const codeAttr = node.attributes?.find((a: any) => a.name === 'code')
+      let code = ''
+
+      if (codeAttr) {
+        if (typeof codeAttr.value === 'string') {
+          code = codeAttr.value
+        } else if (codeAttr.value?.type === 'mdxJsxAttributeValueExpression') {
+          const expr = codeAttr.value.value ?? ''
+          code = expr.match(/^[`'"](.+)[`'"]$/)?.[1] ?? expr
+        }
+      }
+
+      if (!code) return
+
+      const options: any =
+        typeof codeTheme === 'object'
+          ? {
+              themes: { light: codeTheme.light, dark: codeTheme.dark },
+              lang: 'tsx',
+            }
+          : { theme: codeTheme, lang: 'tsx' }
+
+      const html = highlighter.codeToHtml(code, options)
+
+      node.attributes = (node.attributes ?? []).filter(
+        (a: any) => a.name !== 'highlightedHtml',
+      )
+      node.attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'highlightedHtml',
+        value: html,
+      })
+    })
+  }
+}
+
+/**
+ * Custom rehype plugin to perform syntax highlighting at build time for
+ * standard Markdown code blocks.
+ *
+ * Injects 'data-highlighted="true"' and 'highlightedHtml' into the 'pre' tag properties,
+ * which are then consumed by the client-side CodeBlock component.
+ *
+ * @param config - The Boltdocs configuration
+ * @returns A rehype plugin function
+ */
+export function rehypeShiki(config?: BoltdocsConfig) {
+  return async (tree: any) => {
+    const codeTheme = config?.themeConfig?.codeTheme || {
+      light: 'github-light',
+      dark: 'github-dark',
+    }
+    const highlighter = await getShikiHighlighter(codeTheme)
+
+    visit(tree, 'element', (node: any) => {
+      // Handle standard Markdown code blocks
+      if (node.tagName === 'pre' && node.children?.[0]?.tagName === 'code') {
+        const codeNode = node.children[0]
+        const className = codeNode.properties?.className || []
+        const langMatch = className.find((c: string) =>
+          c.startsWith('language-'),
+        )
+        const lang = langMatch ? langMatch.slice(9) : 'text'
+        const code = codeNode.children[0]?.value || ''
+
+        const options: any = { lang }
+        if (typeof codeTheme === 'object') {
+          options.themes = {
+            light: codeTheme.light,
+            dark: codeTheme.dark,
+          }
+        } else {
+          options.theme = codeTheme
+        }
+
+        const html = highlighter.codeToHtml(code, options)
+
+        // Inject highlighted HTML and mark as highlighted for CodeBlock component
+        node.properties.dataHighlighted = 'true'
+        node.properties.highlightedHtml = html
+        node.children = []
+      }
+    })
+  }
+}
+
+const MDX_PLUGIN_VERSION = 'v3'
 
 /**
  * Persistent cache for MDX transformations.
  * Saves results to `.boltdocs/transform-mdx.json.gz`.
  */
-const mdxCache = new TransformCache("mdx");
-let mdxCacheLoaded = false;
+const mdxCache = new TransformCache('mdx')
+let mdxCacheLoaded = false
 
 /**
  * Configures the MDX compiler for Vite using `@mdx-js/rollup`.
  * Includes standard remark and rehype plugins for GitHub Flavored Markdown (GFM),
- * frontmatter extraction, auto-linking headers, and syntax highlighting via `rehype-pretty-code`.
+ * frontmatter extraction, and auto-linking headers.
  *
  * Also wraps the plugin with a persistent cache to avoid re-compiling unchanged MDX files.
  *
@@ -32,62 +190,62 @@ export function boltdocsMdxPlugin(
   compiler = mdxPlugin,
 ): Plugin {
   const extraRemarkPlugins =
-    config?.plugins?.flatMap((p) => p.remarkPlugins || []) || [];
+    config?.plugins?.flatMap((p) => p.remarkPlugins || []) || []
   const extraRehypePlugins =
-    config?.plugins?.flatMap((p) => p.rehypePlugins || []) || [];
+    config?.plugins?.flatMap((p) => p.rehypePlugins || []) || []
 
   const baseMdxPlugin = compiler({
-    remarkPlugins: [remarkGfm, remarkFrontmatter, ...extraRemarkPlugins],
+    remarkPlugins: [
+      remarkGfm,
+      remarkFrontmatter,
+      [remarkShiki, config],
+      ...(extraRemarkPlugins as any[]),
+    ],
     rehypePlugins: [
       rehypeSlug,
-      ...extraRehypePlugins,
-      [
-        rehypePrettyCode,
-        {
-          theme: config?.themeConfig?.codeTheme || "one-dark-pro",
-          keepBackground: false,
-        },
-      ],
+      [rehypeShiki, config],
+      ...(extraRehypePlugins as any[]),
     ],
-    jsxRuntime: "automatic",
-    providerImportSource: "@mdx-js/react",
-  }) as Plugin;
+    jsxRuntime: 'automatic',
+    providerImportSource: '@mdx-js/react',
+  }) as Plugin
 
   // @ts-ignore
   if (baseMdxPlugin.isMock) {
-    console.log("MDX PLUGIN IS MOCKED");
+    console.log('MDX PLUGIN IS MOCKED')
   }
 
   return {
     ...baseMdxPlugin,
-    name: "vite-plugin-boltdocs-mdx",
+    name: 'vite-plugin-boltdocs-mdx',
 
     async buildStart() {
-      hits = 0;
-      total = 0;
+      hits = 0
+      total = 0
       if (!mdxCacheLoaded) {
-        mdxCache.load();
-        mdxCacheLoaded = true;
+        mdxCache.load()
+        mdxCacheLoaded = true
       }
       if (baseMdxPlugin.buildStart) {
-        await (baseMdxPlugin.buildStart as any).call(this);
+        await (baseMdxPlugin.buildStart as any).call(this)
       }
     },
 
     async transform(code, id, options) {
-      if (!id.endsWith(".md") && !id.endsWith(".mdx")) {
-        return (baseMdxPlugin.transform as any)?.call(this, code, id, options);
+      if (!id.endsWith('.md') && !id.endsWith('.mdx')) {
+        return (baseMdxPlugin.transform as any)?.call(this, code, id, options)
       }
 
-      total++;
-      // Create a cache key based on path, content, and config (simplified)
-      const contentHash = crypto.createHash("md5").update(code).digest("hex");
-      const cacheKey = `${id}:${contentHash}`;
+      console.log(`[boltdocs] Transforming MDX: ${id}`)
+      total++
+      // Create a cache key based on path, content, and plugin version
+      const contentHash = crypto.createHash('md5').update(code).digest('hex')
+      const cacheKey = `${id}:${contentHash}:${MDX_PLUGIN_VERSION}`
 
-      const cached = mdxCache.get(cacheKey);
+      const cached = mdxCache.get(cacheKey)
       if (cached) {
-        hits++;
-        return { code: cached, map: null };
+        hits++
+        return { code: cached, map: null }
       }
 
       const result = await (baseMdxPlugin.transform as any).call(
@@ -95,33 +253,27 @@ export function boltdocsMdxPlugin(
         code,
         id,
         options,
-      );
+      )
 
-      if (result && typeof result === "object" && result.code) {
-        mdxCache.set(cacheKey, result.code);
+      if (result && typeof result === 'object' && result.code) {
+        mdxCache.set(cacheKey, result.code)
       }
 
-      return result;
+      return result
     },
 
     async buildEnd() {
-      mdxCache.save();
-      await mdxCache.flush(); // Use instance flush or global flushCache
+      console.log(
+        `[boltdocs] MDX Cache Performance: ${hits}/${total} hits (${Math.round((hits / total) * 100) || 0}%)`,
+      )
+      mdxCache.save()
+      await mdxCache.flush() // Use instance flush or global flushCache
       if (baseMdxPlugin.buildEnd) {
-        await (baseMdxPlugin.buildEnd as any).call(this);
+        await (baseMdxPlugin.buildEnd as any).call(this)
       }
     },
-  };
-}
-
-/**
- * Returns the current MDX cache statistics.
- * @returns An object with total and hit counts
- * @deprecated Removed for performance
- */
-export function getMdxCacheStats() {
-  return { hits: 0, total: 0 };
+  }
 }
 
-let hits = 0;
-let total = 0;
+let hits = 0
+let total = 0

package/src/node/plugin/entry.ts

@@ -1,7 +1,7 @@
-import { normalizePath } from "../utils";
-import type { BoltdocsConfig } from "../config";
-import type { BoltdocsPluginOptions } from "./types";
-import path from "path";
+import { normalizePath } from '../utils'
+import type { BoltdocsConfig } from '../config'
+import type { BoltdocsPluginOptions } from './types'
+import path from 'path'
 
 /**
  * Generates the raw source code for the virtual entry file (`\0virtual:boltdocs-entry`).
@@ -17,14 +17,10 @@ export function generateEntryCode(
 ): string {
   const homeImport = options.homePage
     ? `import HomePage from '${normalizePath(options.homePage)}';`
-    : "";
-  const homeOption = options.homePage ? "homePage: HomePage," : "";
-  const customCssImport = options.customCss
-    ? `import '${normalizePath(options.customCss)}';`
-    : "";
-
+    : ''
+  const homeOption = options.homePage ? 'homePage: HomePage,' : ''
   const pluginComponents =
-    config?.plugins?.flatMap((p) => Object.entries(p.components || {})) || [];
+    config?.plugins?.flatMap((p) => Object.entries(p.components || {})) || []
 
   const componentImports = pluginComponents
     .map(
@@ -34,19 +30,33 @@ export function generateEntryCode(
       ]) => `import * as _comp_${name} from '${normalizePath(path)}';
 const ${name} = _comp_${name}.default || _comp_${name}['${name}'] || _comp_${name};`,
     )
-    .join("\n");
-  const componentMap = pluginComponents.map(([name]) => name).join(", ");
+    .join('\n')
+  const componentMap = pluginComponents.map(([name]) => name).join(', ')
+
+  const docsDirName = path.basename(options.docsDir || 'docs')
 
-  const docsDirName = path.basename(options.docsDir || "docs");
+  const externalEntries = Object.entries(config?.external || {})
+  const externalImports = externalEntries
+    .map(
+      ([_routePath, compPath], i) =>
+        `import _ext_${i} from '${normalizePath(compPath)}';`,
+    )
+    .join('\n')
+  const externalOption =
+    externalEntries.length > 0
+      ? `externalPages: { ${externalEntries
+          .map(([path], i) => `"${path}": _ext_${i}`)
+          .join(', ')} },`
+      : ''
 
   return `
 import { createBoltdocsApp as _createApp } from 'boltdocs/client';
-import 'boltdocs/style.css';
-${customCssImport}
 import _routes from 'virtual:boltdocs-routes';
 import _config from 'virtual:boltdocs-config';
+import _user_mdx_components from 'virtual:boltdocs-mdx-components';
 ${homeImport}
 ${componentImports}
+${externalImports}
 
 _createApp({
   target: '#root',
@@ -56,7 +66,8 @@ _createApp({
   modules: import.meta.glob('/${docsDirName}/**/*.{md,mdx}'),
   hot: import.meta.hot,
   ${homeOption}
-  components: { ${componentMap} },
+  ${externalOption}
+  components: { ${componentMap}${componentMap ? ', ' : ''} ...(_user_mdx_components || {}) },
 });
-`;
+`
 }

package/src/node/plugin/html.ts

@@ -1,4 +1,4 @@
-import type { BoltdocsConfig } from "../config";
+import type { BoltdocsConfig } from '../config'
 
 /**
  * Injects OpenGraph, Twitter, and generic SEO meta tags into the final HTML output.
@@ -9,8 +9,8 @@ import type { BoltdocsConfig } from "../config";
  * @returns The modified HTML string with injected tags
  */
 export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
-  const title = config.themeConfig?.title || "Boltdocs";
-  const description = config.themeConfig?.description || "";
+  const title = config.themeConfig?.title || 'Boltdocs'
+  const description = config.themeConfig?.description || ''
 
   const seoTags = [
     `<meta name="description" content="${description}">`,
@@ -21,7 +21,7 @@ export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
     `<meta name="twitter:title" content="${title}">`,
     `<meta name="twitter:description" content="${description}">`,
     `<meta name="generator" content="Boltdocs">`,
-  ].join("\n    ");
+  ].join('\n    ')
 
   const themeScript = `
     <script>
@@ -39,17 +39,17 @@ export function injectHtmlMeta(html: string, config: BoltdocsConfig): string {
         } catch (e) {}
       })();
     </script>
-  `;
+  `
 
-  html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`);
-  html = html.replace("</head>", `    ${seoTags}\n${themeScript}  </head>`);
+  html = html.replace(/<title>.*?<\/title>/, `<title>${title}</title>`)
+  html = html.replace('</head>', `    ${seoTags}\n${themeScript}  </head>`)
 
-  if (!html.includes("src/main")) {
+  if (!html.includes('src/main')) {
     html = html.replace(
-      "</body>",
+      '</body>',
       '  <script type="module">import "virtual:boltdocs-entry";</script>\n  </body>',
-    );
+    )
   }
 
-  return html;
+  return html
 }