# Markdown 扩展语法参考 > GEO Wiki Pro 自定义 Markdown 扩展语法完整参考手册 --- ## 概述 GEO Wiki Pro 在标准 Markdown 基础上提供了一组扩展语法，用于嵌入视频、3D 模型、提示框等特殊内容。这些扩展语法通过自定义插件实现，位于 `src/plugins/` 目录。 所有扩展语法使用 `:::` 作为标记符。 --- ## 扩展语法一览 | 语法 | 说明 | 示例 | |------|------|------| | `:::video[说明](url)` | 视频嵌入 | `:::video[B站视频](https://bilibili.com/video/BVxxx)` | | `:::model[标题](url)` | 3D 模型下载卡片 | `:::model[电机模型](/media/model.step)` | | `` | 图片（alt 自动显示为图注） | `` | | `[名称](url)` | 文件下载卡片（PDF/DOC等） | `[用户手册](/media/manual.pdf)` | | `::: note/tip/warning/danger` | 提示框 | `:::note\n说明文本\n:::` | | `::: faq` | FAQ 块 | `:::faq\n**Q: ...**\n...\n:::` | --- ## 视频嵌入 ### 基本语法 ```markdown :::video[视频标题](视频URL) ::: ``` ### 使用示例 **Bilibili 视频：** ```markdown :::video[CAN 总线接线教程](https://bilibili.com/video/BV1xx411c7XW) ::: ``` **YouTube 视频：** ```markdown :::video[Arduino CAN Bus Tutorial](https://www.youtube.com/watch?v=dQw4w9WgXcQ) ::: ``` ### 支持的平台 | 平台 | 支持格式 | 说明 | |------|----------|------| | Bilibili | `bilibili.com/video/BVxxx` | 自动嵌入 iframe | | YouTube | `youtube.com/watch?v=xxx` 或 `youtu.be/xxx` | 自动嵌入 iframe | | 其他 | 标准视频 URL | 尝试通用嵌入 | ### 渲染效果 视频嵌入后会显示为一个带有标题说明的响应式视频播放器。在移动端会自动调整尺寸。 ::: note 视频 URL 必须是完整的、可公开访问的地址。不支持需要登录的私有视频。 ::: --- ## 3D 模型下载卡片 ### 基本语法 ```markdown :::model[模型名称](模型文件URL) ::: ``` ### 使用示例 ```markdown :::model[UIM342 电机 3D 模型](/media/uim342-model.step) ::: :::model[UIC320 接线端子](/media/uic320-terminal.stp) ::: ``` ### 支持的格式 | 格式 | 扩展名 | 说明 | |------|--------|------| | STEP | `.step`、`.stp` | 3D CAD 模型 | | STL | `.stl` | 3D 打印模型 | | IGES | `.iges`、`.igs` | 通用 CAD 交换格式 | ### 渲染效果 模型卡片会显示： - 文件图标 - 模型名称 - 文件格式标签 - 下载按钮 点击下载按钮即可获取模型文件。 --- ## 图片 ### 基本语法 ```markdown  ``` ### 使用示例 ```markdown   ``` ### 图片特性 | 特性 | 说明 | |------|------| | 响应式缩放 | 图片自动适应容器宽度 | | 圆角 | 自动添加圆角样式 | | 图注 | alt 文本自动显示为图片下方的说明文字 | | 懒加载 | 图片在滚动到视口时才加载 | ### 图注样式 图片的 alt 文本会自动渲染为居中的图注文字： ```markdown  ``` 渲染效果：图片下方显示 "CAN 总线接线端子特写"。 --- ## 文件下载卡片 ### 基本语法 当链接指向特定文件类型时，会自动渲染为下载卡片： ```markdown [文件显示名称](文件URL) ``` ### 支持的文件类型 | 类型 | 扩展名 | 卡片图标 | |------|--------|----------| | PDF | `.pdf` | PDF 图标 | | Word | `.doc`、`.docx` | Word 图标 | | Excel | `.xls`、`.xlsx` | Excel 图标 | | CAD | `.step`、`.stp`、`.iges` | CAD 图标 | | 压缩包 | `.zip`、`.rar`、`.7z` | 压缩包图标 | ### 使用示例 ```markdown [产品数据手册](/media/uim342-datasheet.pdf) [接线配置文件](/media/wiring-config.zip) [3D 模型文件](/media/uim342-model.step) ``` ### 渲染效果 下载卡片会显示： - 文件类型图标 - 文件名称 - 文件大小（如可用） - 下载按钮 ::: tip 将文件放在 `public/media/` 目录下，使用 `/media/filename.ext` 路径即可自动生成下载卡片。 ::: --- ## 提示框（Admonitions） ### 基本语法 ```markdown ::: 类型 提示框内容... ::: ``` ### 四种类型 #### note（说明） ```markdown ::: note 这是补充说明信息，用于提供额外的背景知识或上下文。 ::: ``` 渲染效果：蓝色边框，左侧带有信息图标。 #### tip（提示） ```markdown ::: tip 这是有用的提示和最佳实践建议。 ::: ``` 渲染效果：绿色边框，左侧带有灯泡图标。 #### warning（警告） ```markdown ::: warning 这是重要的注意事项，需要特别关注。 ::: ``` 渲染效果：黄色边框，左侧带有警告图标。 #### danger（危险） ```markdown ::: danger 这是关键安全信息，操作不当可能导致严重后果。 ::: ``` 渲染效果：红色边框，左侧带有危险图标。 ### 嵌套使用 提示框可以包含 Markdown 内容： ```markdown ::: warning **重要：** 在修改配置文件之前，请先备份。 ```bash cp config.json config.json.bak ``` ::: ``` --- ## FAQ 块 ### 基本语法 ```markdown ::: faq **Q: 问题内容？** 答案内容。 **Q: 另一个问题？** 另一个答案。 ::: ``` ### 使用示例 ```markdown ::: faq **Q: 如何重置设备？** 按住重置按钮 5 秒即可恢复出厂设置。 **Q: CAN 总线最大传输距离是多少？** 在 250 kbps 波特率下，最大传输距离为 30 米。 **Q: 支持哪些开发板？** 支持 Arduino、STM32、树莓派等所有带 CAN 接口的开发板。 ::: ``` ### 渲染效果 FAQ 块会渲染为： - 问题以粗体显示 - 答案紧跟在问题下方 - 各问答之间有适当间距 --- ## 接线图（代码块内） ### 对齐规则 在代码块中绘制接线图时，需要遵循等宽对齐规则： **正确示例（等宽对齐）：** ``` V+ ———— +16~48VDC V− ———— GND CAN_H ———— CAN 总线高 GND ———— 系统地 ``` **错误示例（未对齐）：** ``` V+ ———— +16~48VDC V− ———— GND CAN_H ———— CAN 总线高 GND ———— 系统地 ``` ### 对齐计算 - 每个 ASCII 字符（字母、数字、符号）= 1 列 - 每个 CJK 字符（中文、日文、韩文）= 2 列 - `————`（全角破折号）= 4 列 - 每行的 `————` 必须从相同的字符列开始 **计算示例：** ``` V+ ———— +16~48VDC │ │ │ └── 第 7 列开始（V+ 为 2 列 + 5 空格） └── 第 1 列开始 CAN_H ———— CAN 总线高 │ │ │ └── 第 7 列开始（CAN_H 为 5 列 + 1 空格） └── 第 1 列开始 ``` --- ## 使用注意事项 ### 1. 扩展语法必须完整 每个扩展块必须以 `:::type` 开始，以 `:::` 结束： ```markdown ::: note 内容... ::: ``` 缺少结束标记会导致渲染异常。 ### 2. 空行处理 扩展块内可以包含空行，但扩展块之间建议保留一个空行： ```markdown ::: note 第一个提示框。 ::: ::: tip 第二个提示框。 ::: ``` ### 3. 嵌套限制 扩展语法**不支持**嵌套： ```markdown ::: note ::: tip 这会导致渲染错误。 ::: ::: ``` ### 4. 转义 如果需要在文本中显示 `:::`，可以使用反斜杠转义： ```markdown \::: note 这不会被渲染为提示框。 ::: ``` --- ## 插件开发 扩展语法的实现位于 `src/plugins/` 目录。每个插件导出一个 Markdown-It 插件函数。 ### 插件结构 ``` src/plugins/ video.js # 视频嵌入插件 model.js # 3D 模型卡片插件 callout.js # 提示框插件 faq.js # FAQ 块插件 download.js # 文件下载卡片插件 ``` ### 自定义扩展 如需添加新的扩展语法，参考现有插件实现： ```javascript // src/plugins/my-extension.js export default function myExtension(md) { md.block.ruler.before('fence', 'my_extension', (state, startLine, endLine, silent) => { // 解析逻辑 }); } ``` --- *最后更新: 2026-06-06 | 版本: v3.0.2*