由 leungsekyu 发布于 2025年1月23日 更新于 2025年2月27日

游乐场 | Astro MDX

1. Frontmatter 变量

本篇文章的标题是 游乐场 | Astro MDX，可以通过 frontmatter.title 获取。

标题：游乐场 | Astro MDX

> 标题：{frontmatter.title}

在 MDX 中使用 Frontmatter 变量 🔗

2. 纯 CSS 图标

在 MDX 中允许使用 div 元素，并且 UnoCSS 可以正常工作，因此可以正常使用在 uno.config.ts 里注册的图标集（配置方法请参考下方代码及官方链接）。

1

使用 pnpm 安装 Astro 的 UnoCSS 集成

pnpm add -D unocss

Astro Integration → Installation 🔗

2

2.1 使用 pnpm 安装 @unocss/reset（用于重置浏览器样式）

pnpm add -D @unocss/reset

2.2 在 astro.config.ts 中注册 UnoCSS 集成并重置浏览器样式

import { defineConfig } from 'astro/config'
import UnoCSS from 'unocss/astro'

export default defineConfig({
  integrations: [
    UnoCSS({
      injectReset: true,
    }),
  ],
})

Astro Integration → Style Reset 🔗

3

3.1 使用 pnpm 添加 @iconify-json/logos 图标集

pnpm add -D @iconify-json/logos

SVG Logos 🔗

logos:mdx 🔗

3.2 在 uno.config.ts 中配置 UnoCSS 预设并注册图标集

import { defineConfig, presetWind, presetTypography, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetWind(),
    presetTypography(),
    presetIcons({
      collections: {
        logos: async () => {
          const icons = await import('@iconify-json/logos/icons.json')
          return icons.default
        },
      },
    }),
  ],
})

Wind preset 🔗

Typography preset 🔗

Icons preset 🔗

4

在 MDX 文件中使用

<div class="i-logos-mdx w-26 h-26 -mb-8 -mt-8"></div>

显示效果如下

3. Mermaid 图表

在 Markdown 文件中也能使用！

用法1：使用 remark 插件 remark-mermaidjs

⭐️ 推荐：此用法生成的 Mermaid 图表文字可被选中复制，交互体验更好。

1

使用 pnpm 添加 remark-mermaidjs remark 插件

pnpm add remark-mermaidjs

remark-mermaidjs → Installation 🔗

2

2.1 使用 pnpm 添加 playwright 自动化测试框架

pnpm add playwright

2.2 使用 playwright 安装 chromium 浏览器和相关操作系统依赖项

pnpm exec playwright install --with-deps chromium

remark-mermaidjs → Installation 🔗

Browsers → Install system dependencies 🔗

3

在 astro.config.ts 中注册 remark-mermaidjs remark 插件并配置 Mermaid 图表使用手绘风格

import { defineConfig } from 'astro/config'
import remarkMermaid from 'remark-mermaidjs'

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [
      [
        remarkMermaid,
        {
          mermaidConfig: {
            look: 'handDrawn',
          },
        },
      ],
    ],
  },
})

添加 remark 和 rehype 插件 🔗

4

在 Markdown / MDX 文件中使用 Mermaid 图表

英文

```mermaid
graph LR
  A[Cat] --> B[Cat Pro Max]
```

简体中文

```mermaid
graph LR
  A[猫] --> B[老虎]
```

Emoji

```mermaid
graph LR
  A[🐱] --> B[🐯]
```

英文 + Emoji

```mermaid
graph LR
  A[Cat 🐱] --> B[Cat Pro Max 🐯]
```

简体中文 + Emoji

```mermaid
graph LR
  A[猫 🐱] --> B[老虎 🐯]
```

⚠️ 已知问题：在 Netlify 部署后会出现中文和 Emoji 渲染不全的情况（本站部署在 Netlify 上），但在本地开发环境（macOS Sequoia 15.3.1）均能正常显示。

💭 更新1：可能与 Netlify 用户没有权限安装 Playwright Chromium 浏览器相关操作系统依赖项有关，因为在 Koyeb 使用 Docker 部署（可以正常安装依赖）后显示效果与本地开发环境一致，可点击下方链接查看 Koyeb 的部署效果。

leungsekyu → 游乐场 | Astro MDX（部署在 Koyeb） 🔗

🧐 后续尝试：使用 Puppeteer 替代 Playwright 渲染 Mermaid 图表。

用法2：使用 Mermaid Live Editor

Mermaid Live Editor 🔗

🪧 提示：需要在桌面端浏览器打开

使用方法

编辑图表后在左下方的 Actions 折叠栏中选择导出 SVG 图片或者直接使用生成的 SVG 图片 URL

英文

%%{init: {'look': 'handDrawn'}}%%
graph LR
  A[Cat] --> B[Cat Pro Max]

使用导出的 SVG 图片

使用生成的 SVG 图片 URL

Mermaid Live Editor → 英文 🔗

英文 + Emoji

%%{init: {'look': 'handDrawn'}}%%
graph LR
  A[Cat 🐱] --> B[Cat Pro Max 🐯]

使用导出的 SVG 图片

使用生成的 SVG 图片 URL

Mermaid Live Editor → 英文 + Emoji 🔗

中文 + Emoji

%%{init: {'look': 'handDrawn'}}%%
graph LR
  A[猫 🐱] --> B[老虎 🐯]

使用导出的 SVG 图片

使用生成的 SVG 图片 URL

Mermaid Live Editor → 中文 + Emoji 🔗

⚠️ 已知问题：使用导出的 SVG 图片会在移动端出现 Emoji 右侧有少许遮挡的情况，原因不明。

总结

无论采用哪种用法，均建议使用英文，兼容性最好。

作者：leungsekyu