Skip to content

格式规范

本文档建立了项目中所有文档的一致格式标准。

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) - 谨慎使用

内容组织

页面结构

  1. 介绍 - 页面内容的简要概览
  2. 先决条件 - 开始前需要的内容（如果适用）
  3. 主要内容 - 按逻辑章节组织的核心信息
  4. 示例 - 实际示例和用例
  5. 故障排除 - 常见问题和解决方案（如果适用）
  6. 相关主题 - 链接到相关内容
  7. 下一步 - 阅读此页面后要做什么

章节指南

  • 保持章节专注于单一主题
  • 使用描述性章节标题
  • 为复杂章节包含简要介绍
  • 以明确结果或下一步结束章节

代码格式

代码块

始终指定语言以进行语法高亮：

```bash
# Shell 命令
command --option value

// JavaScript 代码
function example() {
    return "格式化的代码";
}


# 配置文件
key: value
nested:
  option: setting

### 内联代码

使用反引号表示内联代码、命令、文件名和技术术语：

- 命令：`hugo server`
- 文件名：`config.toml`
- 技术术语：`front matter`
- 代码片段：`const variable = "value"`

## 链接和引用

### 内部链接

使用相对路径进行内部文档链接：

```markdown
[链接文本](../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 的描述 |

图片和媒体

图片格式

![描述图片的替代文本](../features/image-optimization.md)

带标题的图片

<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
  • 在更改时审查和更新相关页面
  • 保持示例与最新版本同步