# Markdown 写作指南 > 编写高质量技术文档的完整指南 | v1.0.7 --- ## YAML Frontmatter（必填） 每篇文档必须以 YAML Frontmatter 开头： ```yaml --- title: 文档标题 slug: url-friendly-slug category: 分类slug tags: [标签1, 标签2] author: admin sort: 1 description: 简短描述（对 SEO 重要） language: zh notice: "💡 可选的提示横幅" --- ``` ### 字段说明 | 字段 | 必填 | 说明 | |------|------|------| | `title` | 是 | 文档标题 | | `slug` | 是 | URL 标识符（仅字母、数字、连字符、下划线，最长 200 字符） | | `category` | 是 | 分类 slug（必须已存在） | | `tags` | 是 | 标签数组 `[tag1, tag2]` | | `author` | 是 | 作者名称 | | `sort` | 否 | 排序值（数字，升序，默认 999） | | `description` | 否 | 搜索结果摘要 | | `notice` | 否 | 通知横幅文本 | | `language` | 否 | 语言代码（zh/en/jp） | ::: warning slug 创建后如需修改，可使用 `geo doc slug-rename --slug 旧slug --new-slug 新slug` 命令（会同步更新所有语言版本）。 ::: --- ## 基础 Markdown 语法 ### 标题 ```markdown # 一级标题（仅一个） ## 二级标题 ### 三级标题 #### 四级标题 ``` ### 文本格式 ```markdown **粗体** | *斜体* | ~~删除线~~ | ==高亮== ``` ### 列表 ```markdown - 无序列表 - 子项目 1. 有序列表 2. 第二项 - [x] 任务完成 - [ ] 任务未完成 ``` ### 引用与分隔线 ```markdown > 引用文本 --- ``` ### 链接 ```markdown [内部链接](/docs/slug) [外部链接](https://example.com) [锚点链接](#section-id) ``` ### 表格 ```markdown | 列 1 | 列 2 | 列 3 | |------|------|------| | 数据 | 数据 | 数据 | ``` ### 脚注 ```markdown 这是一个带有脚注的句子[^1]。 [^1]: 这是脚注的内容，显示在页面底部。 ``` 脚注会自动渲染在文档底部，带有分隔线和编号。 --- ## 代码块 ### 基本代码块 ````markdown ```bash npm install ``` ```javascript console.log("Hello"); ``` ```json { "key": "value" } ``` ```` ### 支持的语言 `bash`、`javascript`、`python`、`json`、`yaml`、`css`、`html`、`sql`、`go`、`java`、`rust`、`cpp`、`shell`、`dockerfile`、`nginx` ### 标签页代码块 将多个连续代码块合并为标签页切换视图。在代码块信息后添加 `// [标签名]`： ````markdown ```bash // [Bash] npm install geowiki-cli ``` ```python // [Python] import requests response = requests.get("https://api.example.com") ``` ```javascript // [JavaScript] fetch("https://api.example.com") .then(res => res.json()) ``` ```` 渲染效果：代码块顶部显示标签按钮，点击可切换不同语言的代码。 ::: tip 标签页代码块适合展示同一功能在不同语言中的实现方式。 ::: --- ## Mermaid 图表 使用 `mermaid` 语言标识创建流程图、时序图、甘特图等： ### 流程图 ````markdown ```mermaid graph TD A[开始] --> B{判断} B -->|条件1| C[处理1] B -->|条件2| D[处理2] C --> E[结束] D --> E ``` ```` ### 时序图 ````markdown ```mermaid sequenceDiagram participant A as 用户 participant B as 服务器 A->>B: 发送请求 B->>A: 返回响应 ``` ```` ### 甘特图 ````markdown ```mermaid gantt title 项目计划 section 阶段1 需求分析: 2026-01-01, 7d 设计: 2026-01-08, 5d section 阶段2 开发: 2026-01-13, 14d 测试: 2026-01-27, 7d ``` ```` ### 类图 ````markdown ```mermaid classDiagram class User { +String name +String email +login() } class Post { +String title +String content +publish() } User --> Post : writes ``` ```` ::: note Mermaid 图表会自动适应暗色模式，无需额外配置。 ::: --- ## ECharts 图表 使用 `echarts` 语言标识创建交互式图表： ### 柱状图 ````markdown ```echarts { "title": { "text": "月度访问量" }, "tooltip": {}, "xAxis": { "data": ["1月", "2月", "3月", "4月", "5月", "6月"] }, "yAxis": {}, "series": [{ "name": "访问量", "type": "bar", "data": [120, 200, 150, 80, 70, 110] }] } ``` ```` ### 折线图 ````markdown ```echarts { "title": { "text": "趋势分析" }, "tooltip": { "trigger": "axis" }, "xAxis": { "type": "category", "data": ["周一", "周二", "周三", "周四", "周五"] }, "yAxis": { "type": "value" }, "series": [{ "name": "数据", "type": "line", "data": [100, 150, 130, 180, 160] }] } ``` ```` ### 饼图 ````markdown ```echarts { "title": { "text": "来源分布" }, "tooltip": { "trigger": "item" }, "series": [{ "name": "来源", "type": "pie", "radius": "50%", "data": [ { "value": 335, "name": "直接访问" }, { "value": 310, "name": "搜索引擎" }, { "value": 234, "name": "社交媒体" } ] }] } ``` ```` ::: tip ECharts 图表支持交互操作，鼠标悬停显示详细数据。图表会自动适应暗色模式。 ::: --- ## 网格布局 使用 `:::grid` 创建响应式网格布局，适合并排展示图片或内容块： ### 基本网格 ```markdown :::grid{cols=2} 内容块 1 内容块 2 ::: ``` ### 卡片样式网格 ```markdown :::grid{cols=3 style=card} 卡片内容 1 卡片内容 2 卡片内容 3 ::: ``` | 参数 | 说明 | 默认值 | |------|------|--------| | `cols` | 列数（1-6） | 2 | | `style` | 样式（default / card） | default | ::: note 每个空行分隔的内容块成为一个网格单元。支持 1-6 列。 ::: --- ## 扩展语法 ### 提示框（Callouts） ```markdown ::: note 补充说明信息。 ::: ::: tip 有用的提示。 ::: ::: warning 重要注意事项。 ::: ::: danger 关键安全信息。 ::: ``` ### FAQ 块 ```markdown ::: faq **Q: 问题一？** 回答一。 **Q: 问题二？** 回答二。 ::: ``` ### 数学公式 行内公式：`$E=mc^2$` 块级公式： ```markdown $$ \int_{a}^{b} f(x) dx = F(b) - F(a) $$ ``` ### 视频嵌入 ```markdown :::video[视频说明](https://bilibili.com/video/BVxxx) ::: ``` ### 3D 模型 ```markdown :::model[模型名称](/media/model.step) ::: ``` ### 文件下载 PDF、DOC 等文件自动渲染为下载卡片： ```markdown [用户手册](/media/manual.pdf) ``` ### 图片 图片自动响应式缩放，alt 文本显示为图注： ```markdown  ``` --- ## 提示框类型 | 类型 | 用途 | 边框颜色 | |------|------|----------| | `::: note` | 补充说明 | 蓝色 | | `::: tip` | 提示建议 | 绿色 | | `::: warning` | 注意事项 | 黄色 | | `::: danger` | 安全警告 | 红色 | --- ## 常见问题 **Q: slug 一旦创建能修改吗？** A: 可以。使用 `geo doc slug-rename --slug 旧slug --new-slug 新slug` 命令，会同步更新所有语言版本的 slug。 **Q: 如何编辑非当前语言的文档？** A: 使用 CLI 指定语言：`geo doc update --slug xxx --lang en` **Q: 图片放在哪里？** A: 放在 `public/media/` 目录，引用时用 `/media/filename.ext`。 **Q: 如何让代码块有行号？** A: 系统自动为代码块添加行号，无需手动设置。 **Q: 标签页代码块最多支持几个标签？** A: 建议不超过 5 个，过多会影响显示效果。 **Q: ECharts 图表支持哪些类型？** A: 支持 ECharts 5 的所有图表类型：柱状图、折线图、饼图、散点图、雷达图、热力图等。 --- *最后更新: 2026-07-02 | 版本: v1.0.7*