格式规范
本文档建立了项目中所有文档的一致格式标准。
Front Matter 标准¶
所有文档页面必须包含以下结构的 front matter：
---
title: "页面标题"
description: "简要描述（SEO 最多 160 个字符）"
category: user-guide|developer-guide|features|reference
tags:
- tag1
- tag2
last_updated: YYYY-MM-DD
contributors:
- github-username
related_pages:
- relative/path/to/page.md
difficulty: beginner|intermediate|advanced
---
标题结构¶
层次规则¶
- 每页只使用一个 H1 (
#) - 主标题 - 使用 H2 (
##) 表示主要章节 - 使用 H3 (
###) 表示子章节 - 避免超过 H4 (
####) 的深度
标题格式¶
# 主标题 (H1)
## 主要章节 (H2)
### 子章节 (H3)
#### 子子章节 (H4) - 谨慎使用
内容组织¶
页面结构¶
- 介绍 - 页面内容的简要概览
- 先决条件 - 开始前需要的内容（如果适用）
- 主要内容 - 按逻辑章节组织的核心信息
- 示例 - 实际示例和用例
- 故障排除 - 常见问题和解决方案（如果适用）
- 相关主题 - 链接到相关内容
- 下一步 - 阅读此页面后要做什么
章节指南¶
- 保持章节专注于单一主题
- 使用描述性章节标题
- 为复杂章节包含简要介绍
- 以明确结果或下一步结束章节
代码格式¶
代码块¶
始终指定语言以进行语法高亮：
```bash
# Shell 命令
command --option value
```
```javascript
// JavaScript 代码
function example() {
return "格式化的代码";
}
```
```yaml
# 配置文件
key: value
nested:
option: setting
```
内联代码¶
使用反引号表示内联代码、命令、文件名和技术术语：
- 命令：
hugo server - 文件名：
config.toml - 技术术语：
front matter - 代码片段：
const variable = "value"
链接和引用¶
内部链接¶
使用相对路径进行内部文档链接：
[链接文本](../user-guide/getting-started.md)
[另一个链接](../user-guide/content-creation.md)
外部链接¶
包含描述性文本，在适当时在新标签页中打开：
[Hugo 文档](https://gohugo.io/documentation/)
交叉引用¶
在相关主题之间创建清晰的交叉引用：
有关更多信息，请参阅 [配置参考](../reference/configuration.md)。
!!! info "相关主题"
此功能与 [图片优化](../features/image-optimization.md) 配合工作。
提示和标注¶
使用 Material for MkDocs 提示语法：
信息¶
!!! info "信息标题"
帮助用户理解上下文的重要信息。
提示¶
!!! tip "专业提示"
有用的提示和最佳实践。
警告¶
!!! warning "重要"
重要警告或注意事项。
危险/错误¶
!!! danger "安全警告"
关键安全信息或危险操作。
注释¶
!!! note "注释"
附加注释和澄清。
列表和表格¶
无序列表¶
- 项目 1
- 项目 2
- 子项目 2.1
- 子项目 2.2
- 项目 3
有序列表¶
1. 第一步
2. 第二步
1. 子步骤 2.1
2. 子步骤 2.2
3. 第三步
任务列表¶
- [x] 已完成的任务
- [ ] 待处理的任务
- [ ] 另一个待处理的任务
表格¶
| 列 1 | 列 2 | 列 3 |
|------|------|------|
| 值 1 | 值 2 | 值 3 |
| 值 4 | 值 5 | 值 6 |
对于配置表格：
| 选项 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `option1` | string | `"default"` | 选项 1 的描述 |
| `option2` | boolean | `false` | 选项 2 的描述 |
图片和媒体¶
图片格式¶
带标题的图片¶
<figure>
<img src="../features/image-optimization.md" alt="替代文本">
<figcaption>描述图片的标题</figcaption>
</figure>
图表¶
尽可能使用 Mermaid 创建图表：
```mermaid
graph TD
A[开始] --> B{决策}
B -->|是 | C[操作 1]
B -->|否| D[操作 2]
C --> E[结束]
D --> E
```
写作风格¶
语调和语气¶
- 使用主动语态
- 用第二人称（"您"）写说明
- 简洁明了
- 对当前功能使用现在时
- 对计划功能使用将来时
技术写作¶
- 首次使用时定义技术术语
- 在整个过程中使用一致的术语
- 为复杂概念包含示例
- 为技术决策提供上下文
可访问性¶
- 使用描述性链接文本（避免"点击这里"）
- 为所有图片包含替代文本
- 使用适当的标题层次
- 确保示例中有足够的颜色对比
文件命名¶
文档文件¶
- 使用小写和连字符：
getting-started.md - 具有描述性：
shortcode-reference.md - 避免缩写：
configuration.md而不是config.md
图片文件¶
- 使用描述性名称：
architecture-diagram.png - 包含上下文：
user-guide-setup-screenshot.png - 使用小写和连字符
元数据和 SEO¶
页面描述¶
- 保持在 160 个字符以下
- 包含主要关键词
- 具有描述性和可操作性
标签¶
- 使用小写
- 具有特定性：
content-creation而不是content - 每页包含 2-5 个相关标签
- 在相似页面中保持一致性
审查清单¶
发布文档之前：
- Front matter 完整且准确
- 标题遵循适当的层次
- 所有代码块都指定了语言
- 链接经过测试且正常工作
- 图片有替代文本
- 拼写和语法正确
- 内容遵循既定的结构
- 适当链接了相关页面
- 示例经过测试且正常工作
模板使用¶
为每种文档类型使用适当的模板：
- 用户指南: 使用
user-guide-template.md - 开发者指南: 使用
developer-guide-template.md - 功能: 使用
feature-template.md - 参考: 根据需要调整模板
维护¶
- 在进行重大更改时更新
last_updated字段 - 在进行实质性编辑时将您的 GitHub 用户名添加到
contributors - 在更改时审查和更新相关页面
- 保持示例与最新版本同步