Astro 项目中 MDX 文件内渲染 Mermaid 的实现原理

// astro.config.ts
import { remarkMermaid } from './src/plugins/remark-mermaid.ts'

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMath, remarkMermaid],
    rehypePlugins: [
      [rehypeKatex, {}],
      rehypeHeadingIds,
      [rehypeAutolinkHeadings, { /* ... */ }]
    ],
    // ...其他配置
  }
})

// src/plugins/remark-mermaid.ts
import type { Root } from 'mdast'
import type { Plugin } from 'unified'
import { visit } from 'unist-util-visit'

export const remarkMermaid: Plugin<[], Root> = function () {
  return function (tree) {
    // 遍历 AST 中的所有节点
    visit(tree, 'code', (node, index, parent) => {
      // 只处理 mermaid 语言的代码块
      if (node.lang !== 'mermaid') {
        return
      }

      if (!parent || index === undefined) {
        return
      }

      // 生成唯一 ID 避免冲突
      const id = `mermaid-${Math.random().toString(36).substring(2, 11)}`

      // 创建包含脚本的 HTML 节点
      const htmlNode = {
        type: 'html',
        value: `
<div class="mermaid-container">
  <div id="${id}" class="mermaid-diagram" data-code="${node.value.replace(/"/g, '&quot;')}">${node.value}</div>
</div>

<script type="module">
  // 动态加载和渲染逻辑
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  // ... 渲染脚本，即客户端渲染核心逻辑
</script>
        `
      }

      // 替换原始代码块节点
      parent.children[index] = htmlNode as any
    })
  }
}

// 嵌入在 HTML 中的渲染脚本
async function renderMermaidDiagrams() {
  const currentTheme = getCurrentTheme()
  configureMermaid(currentTheme)

  const diagrams = document.querySelectorAll('.mermaid-diagram')

  for (const diagram of diagrams) {
    const element = diagram

    // 获取原始代码
    let code = element.dataset.code || element.textContent?.trim()

    if (!code || element.dataset.rendered === 'true') continue

    try {
      // 清除之前的内容
      element.innerHTML = ''

      // 渲染新的图表
      const { svg } = await mermaid.render(element.id + '-svg', code)
      element.innerHTML = svg
      element.dataset.rendered = 'true'

      // 添加响应式样式
      const svgElement = element.querySelector('svg')
      if (svgElement) {
        svgElement.style.maxWidth = '100%'
        svgElement.style.height = 'auto'
        svgElement.style.maxHeight = '720px'
      }
    } catch (error) {
      console.error('Mermaid rendering error:', error)
      // 优雅降级：显示原始代码
      element.innerHTML = `
        <pre class="mermaid-error"><code>${code}</code></pre>
        <p class="mermaid-error-message">Failed to render Mermaid diagram</p>
      `
    }
  }
}

// 主题检测和配置
function getCurrentTheme() {
  const isDark = document.documentElement.classList.contains('dark') ||
                document.body.classList.contains('dark') ||
                document.documentElement.getAttribute('data-theme') === 'dark'
  return isDark ? 'dark' : 'light'
}

function configureMermaid(theme) {
  const config = {
    startOnLoad: false,
    theme: theme === 'dark' ? 'dark' : 'default',
    themeVariables: {
      primaryColor: theme === 'dark' ? '#3b82f6' : '#2563eb',
      primaryTextColor: theme === 'dark' ? '#f8fafc' : '#1e293b',
      primaryBorderColor: theme === 'dark' ? '#475569' : '#cbd5e1',
      lineColor: theme === 'dark' ? '#64748b' : '#475569',
      // ... 更多主题变量
    },
    fontFamily: 'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto',
    fontSize: 14
  }
  
  mermaid.initialize(config)
}

// 监听主题变化
function watchThemeChanges() {
  const observer = new MutationObserver((mutations) => {
    mutations.forEach((mutation) => {
      if (mutation.type === 'attributes' &&
          (mutation.attributeName === 'class' || mutation.attributeName === 'data-theme')) {
        // 重置渲染状态并重新渲染
        document.querySelectorAll('.mermaid-diagram').forEach(el => {
          el.dataset.rendered = 'false'
        })
        setTimeout(renderMermaidDiagrams, 100)
      }
    })
  })

  observer.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ['class', 'data-theme']
  })
}

// Markdown AST 中的代码块节点结构
interface CodeNode {
  type: 'code'
  lang: string | null     // 语言标识，如 'mermaid'
  meta: string | null     // 元信息
  value: string          // 代码内容
}

// 转换后的 HTML 节点结构
interface HtmlNode {
  type: 'html'
  value: string          // HTML 字符串
}