# Markdown 扩展语法参考 > GEO Wiki Pro 自定义 Markdown 扩展语法完整参考手册 --- ## 概述 GEO Wiki Pro 在标准 Markdown 基础上提供了一组扩展语法，用于嵌入视频、3D 模型、分栏布局、提示框等特殊内容。这些扩展语法通过自定义插件实现，位于 `src/plugins/` 目录。 所有扩展语法使用 `:::` 作为标记符。 --- ## 扩展语法一览 | 语法 | 说明 | 示例 | |------|------|------| | `:::grid{cols=N}` | 分栏布局 | `:::grid{cols=2}` | | `:::video[说明](url)` | 视频嵌入 | `:::video[B站视频](https://bilibili.com/video/BVxxx)` | | `:::model[标题](url)` | 3D 模型下载卡片 | `:::model[电机模型](/media/model.step)` | | `::: note/tip/warning/danger` | 提示框 | `:::note\n说明文本\n:::` | | `::: faq` | FAQ 块 | `:::faq\n**Q: ...**\n...\n:::` | | `:::tabs` | 选项卡 | `:::tabs\n...tabs content\n:::` | | `` | 图片（alt 自动显示为图注） | `` | | `[名称](url)` | 文件下载卡片（PDF/DOC等） | `[用户手册](/media/manual.pdf)` | --- ## 分栏布局（Grid） ### 基本语法 ```markdown :::grid{cols=2} 内容块 1 内容块 2 ::: ``` ### 支持的列数 | 参数 | 说明 | |------|------| | `cols=1` | 单列（默认） | | `cols=2` | 两列 | | `cols=3` | 三列 | | `cols=4` | 四列 | | `cols=5` | 五列 | | `cols=6` | 六列 | ### 使用示例 **两列图片：** ```markdown :::grid{cols=2}   ::: ``` **三列图片：** ```markdown :::grid{cols=3}    ::: ``` **图文混排：** ```markdown :::grid{cols=2}  ### 接线说明 1. V+ 接电源正极 2. V− 接电源负极 3. CAN_H 接总线高 4. CAN_L 接总线低 ::: ``` ### 渲染规则 - 每个空行分隔的内容块成为一个独立的格子 - 图片会自动响应式缩放 - 支持图片、文字、列表等任意 Markdown 内容 - 移动端自动降为单列显示 ::: warning 分栏布局在编辑器中显示为源码，预览和发布后才会渲染为分栏效果。 ::: --- ## 视频嵌入 ### 基本语法 ```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 格式 | | IGES | `.igs`, `.iges` | 通用 CAD 交换格式 | ### 渲染效果 3D 模型会渲染为一个下载卡片，包含： - 模型名称 - 文件格式标签 - 下载按钮 --- ## 提示框（Admonitions） ### 基本语法 ```markdown ::: note 补充说明信息。 ::: ::: tip 有用的提示和最佳实践。 ::: ::: warning 重要的注意事项。渲染为黄色边框。 ::: ::: danger 关键安全信息。渲染为红色边框。 ::: ``` ### 使用示例 ```markdown ::: note 此功能需要固件 v2.0 以上版本支持。 ::: ::: tip 建议使用屏蔽双绞线以提高抗干扰能力。 ::: ::: warning 接线前请断开电源，否则可能损坏设备。 ::: ::: danger 高压危险！操作前请确保电源已关闭并放电。 ::: ``` ### 渲染效果 | 类型 | 边框颜色 | 用途 | |------|----------|------| | `note` | 蓝色 | 补充说明 | | `tip` | 绿色 | 建议和技巧 | | `warning` | 黄色 | 注意事项 | | `danger` | 红色 | 危险警告 | --- ## FAQ 块 ### 基本语法 ```markdown ::: faq **Q: 问题一？** 回答内容。 **Q: 问题二？** 回答内容。 ::: ``` ### 使用示例 ```markdown ::: faq **Q: 如何重置设备？** 按住重置按钮 5 秒钟，直到指示灯闪烁。 **Q: 最大线缆长度是多少？** CAN 总线在 250 kbps 下最大 30 米。 **Q: 支持哪些操作系统？** 支持 Windows 10+、macOS 12+、Linux（Ubuntu 20.04+）。 ::: ``` ### 渲染效果 FAQ 块会渲染为可折叠的问答列表，便于用户快速查找信息。 --- ## 选项卡（Tabs） ### 基本语法 ```markdown :::tabs Tab1 标签 内容 1 Tab2 标签 内容 2 ::: ``` ### 使用示例 ```markdown :::tabs Windows 下载安装包后双击运行。 macOS 拖拽到 Applications 文件夹。 Linux 运行 `sudo apt install geowiki`。 ::: ``` --- ## 图片 ### 基本语法 ```markdown  ``` ### 使用示例 ```markdown   ``` ### 图片特性 - 自动响应式缩放（最大宽度 100%） - 自动圆角 - alt 文本自动显示为图注（居中、灰色文字） - 支持懒加载 ::: note 图片必须先通过管理后台上传到 `public/media/` 目录，然后使用 `/media/文件名` 路径引用。 ::: --- ## 文件下载卡片 PDF、DOC、STEP 等文件链接会自动渲染为下载卡片。 ### 基本语法 ```markdown [显示名称](/media/文件名.ext) ``` ### 使用示例 ```markdown [用户手册](/media/user-manual.pdf) [产品规格书](/media/product-spec.docx) [电机 3D 模型](/media/motor.step) ``` ### 支持的格式 | 格式 | 扩展名 | 标签颜色 | |------|--------|----------| | PDF | `.pdf` | 红色 | | Word | `.doc`, `.docx` | 蓝色 | | STEP | `.step`, `.stp` | 蓝色 | | IGES | `.igs`, `.iges` | 蓝色 | | 视频 | `.mp4`, `.webm` | 紫色 | | 音频 | `.mp3`, `.wav`, `.ogg` | 绿色 | | 文本 | `.txt`, `.md` | 灰色 | ### 渲染效果 文件下载卡片包含： - 文件类型图标 - 格式标签 - 文件名 - 下载按钮 --- ## 接线图对齐 在代码块中绘制接线图时，左列需要等宽对齐： **正确（等宽对齐）：** ``` V+ ———— +16~48VDC V− ———— GND CAN_H ———— CAN 总线高 GND ———— 系统地 ``` **对齐规则：** - `————`（全角破折号，每段 2 个字符）必须在每行相同的字符列开始 - 每个 ASCII 字符 = 1 列，每个 CJK 字符 = 2 列 - 推荐使用 ASCII 连字符（`-------`）以简化对齐 --- ## 插件文件说明 | 文件 | 功能 | |------|------| | `markdown-it-grid.js` | 分栏布局插件 | | `markdown-it-video.js` | 视频嵌入插件 | | `markdown-it-model.js` | 3D 模型卡片插件 | | `markdown-it-file-card.js` | 文件下载卡片插件 | | `markdown-it-tabs.js` | 选项卡插件 | --- *最后更新: 2026-07-02 | 版本: v1.0.7*