# Markdown 写作指南 > 在 GEO Wiki Pro 中编写高质量技术文档的完整指南 --- ## 概述 GEO Wiki Pro 使用 Markdown 作为文档编写格式。每篇文档以 YAML Frontmatter 开头，正文支持标准 Markdown 语法和扩展语法。 本文档将介绍编写规范、最佳实践和常见注意事项。 --- ## YAML Frontmatter 每篇文档**必须**以 YAML Frontmatter 开头，用 `---` 包围： ```yaml --- title: CAN Bus Protocol slug: can-bus-protocol category: can-motion tags: [can-bus, protocol] author: admin sort: 1 description: Brief description for search results --- ``` ### 必填字段 | 字段 | 说明 | 示例 | |------|------|------| | `title` | 文档标题 | `CAN Bus Protocol` | | `slug` | URL 标识符（仅字母、数字、连字符、下划线） | `can-bus-protocol` | | `category` | 分类 slug（必须已存在） | `can-motion` | | `tags` | 标签数组 | `[can-bus, protocol]` | | `author` | 作者名称 | `admin` | ### 可选字段 | 字段 | 说明 | 示例 | |------|------|------| | `sort` | 排序值（数字，按升序排列，默认 999） | `1` | | `description` | 搜索结果摘要 | `CAN bus overview...` | | `notice` | 通知横幅文本 | `This is a beta feature.` | | `published_at` | 发布时间 | `2026-05-20T10:30:00Z` | | `updated_at` | 更新时间 | `2026-06-01T15:00:00Z` | ### Slug 规则 - 必须匹配 `/^[\w-]+$/`（仅字母、数字、连字符、下划线） - 最大长度：200 个字符 - 推荐使用纯 ASCII 字符以确保 URL 兼容性 - 不能包含 `..`、`/`、`\`、`\0` - 系统会自动检查 slug 去重 ::: warning slug 一旦创建不可修改，因为它被用作文件名和 URL 路径。请选择一个简洁且有意义的 slug。 ::: --- ## 共享字段与独立字段 ### 共享字段（跨语言同步） 以下字段在所有语言版本之间自动同步： - `category` - `tags` - `author` - `sort` 当你更新其中一种语言的共享字段时，`syncSharedFields()` 会自动将这些值广播到其他语言版本。 ### 独立字段（各语言独立） - `title` - `description` - `content` - `notice` - `updated_at` - `published_at` ::: note 编写多语言文档时，只需为每种语言设置独立字段的内容。共享字段只需设置一次。 ::: --- ## 标题层级 ```markdown # 一级标题（文档标题，每篇文档仅一个） ## 二级标题（主要章节） ### 三级标题（子章节） #### 四级标题（更细的分类） ``` **最佳实践：** - 每篇文档只使用一个 `#` 标题 - 使用 `##` 和 `###` 构建文档结构 - 标题层级不要跳跃（如从 `##` 直接到 `####`） --- ## 文本格式 ### 强调 ```markdown **粗体文本** *斜体文本* ~~删除线文本~~ ``` ### 列表 **无序列表：** ```markdown - 第一项 - 第二项 - 子项目 - 子项目 ``` **有序列表：** ```markdown 1. 第一步 2. 第二步 3. 第三步 ``` ### 引用 ```markdown > 这是一段引用文本。 > 可以跨多行。 ``` ### 分隔线 ```markdown --- ``` --- ## 链接 ### 内部链接 内部文档链接使用文档 slug 作为 URL： ```markdown See [CAN Bus Protocol](/docs/can-bus-protocol) for details. ``` ### 外部链接 ```markdown [Visit GitHub](https://github.com/example) ``` ### 锚点链接 ```markdown [跳转到安装章节](#安装步骤) ``` --- ## 图片与媒体 ### 图片 使用相对路径引用 `public/media/` 目录中的图片： ```markdown  ``` 图片特性： - 自动响应式缩放 - 自动圆角 - alt 文本自动显示为图注 ### 视频嵌入 使用扩展语法嵌入视频： ```markdown :::video[视频说明](https://bilibili.com/video/BVxxx) ::: ``` 支持平台： - Bilibili - YouTube - 其他标准视频 URL ### 3D 模型 ```markdown :::model[模型名称](/media/model.step) ::: ``` ### 文件下载 PDF、DOC、STEP 等文件自动渲染为下载卡片： ```markdown [用户手册](/media/manual.pdf) ``` --- ## 代码 ### 行内代码 ```markdown 使用 `git clone` 命令克隆仓库。 ``` ### 代码块 ````markdown ```bash # 安装依赖 npm install ``` ```python import os print("Hello, World!") ``` ```json { "name": "example", "version": "1.0.0" } ``` ```` 支持的语言标识：`bash`、`python`、`javascript`、`json`、`yaml`、`cpp`、`csharp`、`java`、`html`、`css` 等。 ### 接线图对齐 在代码块中绘制接线图时，左列需要等宽对齐： **正确（等宽对齐）：** ``` V+ ———— +16~48VDC V− ———— GND CAN_H ———— CAN 总线高 GND ———— 系统地 ``` **对齐规则：** - `————`（全角破折号，每段 2 个字符）必须在每行相同的字符列开始 - 每个 ASCII 字符 = 1 列，每个 CJK 字符 = 2 列 - 推荐使用 ASCII 连字符（`-------`）以简化对齐 --- ## 表格 ```markdown | 列标题 1 | 列标题 2 | 列标题 3 | |----------|----------|----------| | 单元格 1 | 单元格 2 | 单元格 3 | | 单元格 4 | 单元格 5 | 单元格 6 | ``` --- ## 提示框（Admonitions） GEO Wiki Pro 支持多种提示框类型： ```markdown ::: note 补充说明信息。 ::: ::: tip 有用的提示和最佳实践。 ::: ::: warning 重要的注意事项。渲染为黄色边框。 ::: ::: danger 关键安全信息。渲染为红色边框。 ::: ``` --- ## FAQ 块 ```markdown ::: faq **Q: How do I reset the device?** Press and hold the reset button for 5 seconds. **Q: What is the maximum cable length?** 30 meters for CAN bus at 250 kbps. ::: ``` --- ## 常见错误与注意事项 ### 1. 不要直接编辑文件系统 所有文件写入必须通过 `saveDoc()` 或 `saveDb()`，不要使用 `fs.writeFileSync` 直接写入。 ### 2. Slug 不可修改 一旦创建，slug 用于文件名和 URL。修改 slug 等于创建新文档。 ### 3. 共享字段同步 更新 `category`、`tags`、`author`、`sort` 时会影响所有语言版本。 ### 4. 图片路径 图片必须放在 `public/media/` 目录下，使用 `/media/filename.ext` 路径引用。 ### 5. 编码规范 所有用户可见文本必须通过 `t()` 函数（i18n），不要硬编码字符串。 --- ## 写作检查清单 - [ ] YAML Frontmatter 包含所有必填字段 - [ ] slug 符合命名规范（ASCII、无特殊字符） - [ ] 标题层级正确（一个 `#`，多个 `##`/`###`） - [ ] 代码块指定了正确的语言标识 - [ ] 内部链接使用 `/docs/slug` 格式 - [ ] 图片使用 `/media/` 相对路径 - [ ] 表格格式正确 - [ ] 接线图对齐 - [ ] 使用提示框标注重要信息 - [ ] 描述字段简洁且有搜索价值 --- *最后更新: 2026-06-06 | 版本: v3.0.2*