@vitepress-plugin/markmap

一个强大的 VitePress 插件，用于在 Markdown 中优雅地渲染交互式脑图。基于 markmap-lib 和 markmap-view 构建。

✨ 特性

• 📝 简单易用：使用标准的 Markdown 容器语法，无需额外学习
• 🚀 开箱即用：自动注入所有必需的依赖和组件，无需额外配置
• ⚡ 高效能：基于 markmap-lib 和 markmap-view，渲染性能优异
• 🎯 灵活配置：提供全局和局部的配置选项，满足多种需求

📦 安装

# 使用 npm
npm install @vitepress-plugin/markmap

# 使用 pnpm
pnpm add @vitepress-plugin/markmap

# 使用 yarn
yarn add @vitepress-plugin/markmap

🚀 快速开始

1. 配置插件

在 .vitepress/config.mts 中：

import { defineConfig } from 'vitepress'
import markmapPlugin from '@vitepress-plugin/markmap'

export default defineConfig({
  vite: {
    plugins: [
      markmapPlugin(),
    ],
  },
})

2. 在 Markdown 中使用

:::markmap
---
containerHeight: 500
markmap:
  color: red
  maxInitialScale: 2
  spacingVertical: 16
  spacingHorizontal: 50
---
# Root Node
* Branch 1
  -  Leaf 1.1
  -  Leaf 1.2
* Branch 2
  - Leaf 2.1
  - Leaf 2.2
:::

🎯 配置选项

插件级配置

| 选项 | 类型 | 默认值 | 说明 | |-----|------|--------|------| | name | string | 'markmap' | 自定义容器名称 | | containerHeight | string | number | 300 | 全局自定义容器高度 | | theme | light | dark | 默认和vitepress主题一致 | 全局主题 |

容器级属性

在单个容器中可以覆盖全局配置：
支持使用 YAML frontmatter，并使用 gray-matter 解析。frontmatter 必须位于 容器的顶部，并且需要在三条虚线之间采用有效的 YAML 格式。例如：

:::markmap
---
containerHeight: 500
markmap:
  color: red
---

...
:::

| 选项 | 类型 | 默认值 | 说明 | |-----|------|--------|------| | containerHeight | string | number | 300 | 自定义容器高度 | | theme | light | dark | 默认和vitepress主题一致 | 主题 | | markmap | object | / | 自定义脑图配置 | | markmap:color | string | / | 颜色 | | markmap:spacingHorizontal | number | 24 | 水平方向间隔距离 | | markmap:spacingVertical | number | 10 | 垂直方向间隔距离 | | markmap:maxInitialScale | number | 1 | 最大的初始放大倍数 | | markmap:duration | number | 500 | 展开动画时长(sm) | | markmap:embedGlobalCSS | boolean | true | 是否嵌入全局CSS | | markmap:autoFit | boolean | false | | | markmap:fitRatio | number | 0.95 | 适合缩放比例 | | markmap:initialExpandLevel | number | -1 | 初始展开层级(-1： 全部展开) | | markmap:zoom | boolean | true | 是否可以缩放(false 时不影响toolbar的缩放操作) | | markmap:pan | boolean | true | 是否可以滚动 | | markmap:scrollForPan | boolean | Macintosh: true 其他: false | | | markmap:toggleRecursively | boolean | false | |

🏗️ 项目架构

/
├── src/
│   ├── index.ts          # 插件主入口
│   ├── markmap.vue       # Vue 3 脑图组件
│   ├── types.ts          # TypeScript 类型定义
│   └── utils.ts          # 工具函数（Markdown 解析等）
├── vite.config.ts        # Vite 构建配置
├── tsconfig.json         # TypeScript 配置
├── package.json          # 项目配置
└── README.md             # 项目文档

🔧 核心文件说明

src/index.ts - 插件主文件

• 实现了 Vite 插件接口
• 自动转换 Markdown 中的脑图容器
• 处理热模块替换（HMR）
• 导出类型定义和工具函数

关键功能：

• transform 钩子：转换 Markdown 容器为组件调用
• resolveId 钩子：处理虚拟模块导入
• load 钩子：返回虚拟模块内容

src/markmap.vue - Vue 3 组件

• 提供交互式脑图渲染
• 集成 markmap-lib（Markdown → 脑图结构）
• 集成 markmap-view（脑图可视化和交互）

关键特性：

• 响应式数据绑定
• 实时更新和重新渲染

src/types.ts - 类型定义

提供完整的 TypeScript 类型支持

🎨 样式定制

在 VitePress 主题中添加自定义 CSS：

/* .vitepress/theme/custom.css */

.markmap-container {
  ...
}

🐛 常见问题

Q: 脑图不显示？

A: 检查以下几点：

• Markdown 语法是否正确

Q: 如何改变默认高度？

A: 在在容器中指定 containerHeight 属性

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE

🔗 相关链接

• Markmap 官网
• markmap-lib
• VitePress 文档
• Vite 插件文档

👨‍💻 作者

PaddyWang - GitHub

给个 Star ⭐ 如果这个项目对你有帮助！