Skip to content

文档贡献指南

本文档为 Hugo 网站文档贡献提供了全面的指导。遵循这些指南可确保文档的一致性、质量和可维护性。

概述

我们的文档面向多类受众：

  • 终端用户：内容创作者和网站访问者
  • 开发者：贡献者和维护者
  • 管理员：网站运营和部署管理者

所有贡献需兼顾上述受众，为每类用户提供适当的深度和清晰度。

入门指南

前置条件

在贡献文档前，请：

  1. 阅读相关板块的现有文档
  2. 了解你的贡献面向的目标受众
  3. 查阅风格指南和格式标准
  4. 按照设置指南搭建开发环境

贡献流程

  1. 创建功能分支进行文档修改
  2. 遵循既定模板撰写新内容
  3. 使用验证工具测试你的更改
  4. 提交带有清晰描述的拉取请求
  5. 及时、充分地响应评审反馈

内容标准

写作风格

清晰与简洁：

  • 使用适合目标受众的简明语言
  • 避免不必要的术语（如需使用请加以解释）
  • 尽量使用主动语态
  • 保持句子和段落简短

语气与风格：

  • 保持专业、乐于助人的语气
  • 指令直接、可操作
  • 使用包容性语言，欢迎所有用户
  • 不假设用户已有相关知识或经验

结构与组织：

  • 先介绍最重要的信息
  • 使用清晰的标题层级组织内容
  • 先提供背景再展开细节
  • 包含实际示例和用例

技术准确性

代码示例：

  • 所有代码示例需经过测试
  • 使用真实、实用的案例
  • 必要时附上预期输出
  • 示例需与最新版本保持一致

操作流程：

  • 步骤需逐一验证
  • 补充前置条件信息
  • 提及可能的问题或变体
  • 提供故障排查建议

链接与参考：

  • 验证所有内部和外部链接
  • 使用描述性链接文本（避免“点击这里”）
  • 外部参考需权威且及时
  • 对外部依赖提供备用信息

内容类型与模板

用户指南

目的： 帮助用户完成具体任务或理解功能

模板结构：

---
title: "描述性标题"
description: "简要说明用户将学到什么"
date: YYYY-MM-DD
lastmod: YYYY-MM-DD
categories: ["user-guide"]
tags: ["相关", "标签"]
weight: 10
---

# 页面标题

## 概述
简要介绍本指南内容及适用对象。

## 前置条件
- 列出所有要求
- 包含设置指南链接
- 说明技能水平假设

## 步骤说明

### 步骤 1：首要操作
清晰指令，必要时附代码示例。

### 步骤 2：后续操作
按逻辑顺序继续说明。

## 示例
展示实际应用场景。

## 故障排查
常见问题及解决方法。

## 相关文档
链接至相关指南和参考资料。

开发者指南

目的： 为开发者和贡献者提供技术信息

模板结构：

---
title: "技术主题"
description: "技术描述"
date: YYYY-MM-DD
lastmod: YYYY-MM-DD
categories: ["developer-guide"]
tags: ["开发", "技术"]
weight: 10
---

# 技术主题

## 概述
技术介绍及范围说明。

## 架构/设计
技术细节与设计决策。

## 实现
代码示例及技术流程。

## API 参考（如适用）
详细 API 文档。

## 测试
测试流程及示例。

## 贡献指南
如何参与该领域的贡献。

功能文档

目的： 针对具体功能的全面说明

模板结构：

---
title: "功能名称"
description: "功能描述"
date: YYYY-MM-DD
lastmod: YYYY-MM-DD
categories: ["features"]
tags: ["功能名称"]
weight: 10
---

# 功能名称

## 概述
功能作用及价值说明。

## 配置
如何配置和启用该功能。

## 使用方法
使用方法及示例。

## 高级用法
复杂场景与自定义说明。

## 故障排查
常见问题及解决方法。

## API 参考
技术参考（如适用）。

参考文档

目的： 快速参考材料和全面选项列表

模板结构：

---
title: "参考：主题"
description: "主题快速参考"
date: YYYY-MM-DD
lastmod: YYYY-MM-DD
categories: ["reference"]
tags: ["参考"]
weight: 10
---

# 参考：主题

## 快速参考
关键信息汇总表或列表。

## 详细参考
全面列表及说明。

## 示例
参考项的使用示例。

## 相关内容
链接至相关文档。

格式标准

Markdown 规范

标题：

  • 使用 ATX 风格标题（# 语法）
  • # 后需加空格
  • 标题使用句式首字母大写
  • 保持层级逻辑，不跳级

列表：

  • 无序列表用 -
  • 有序列表用 1.（自动编号）
  • 保持缩进一致
  • 列表项结构统一

代码块：

  • 指定语言以高亮语法
  • 示例变量名具描述性
  • 复杂代码加注释
  • 所有代码需测试

链接：

  • 使用描述性链接文本
  • 内部链接优先用相对路径
  • 外部链接加 title 属性
  • 定期检查所有链接

图片：

  • 添加描述性 alt 文本
  • 优化图片（优选 WebP 格式）
  • 保持尺寸和样式一致
  • 必要时加说明文字

Front Matter 标准

必填字段：

---
title: "页面标题"           # 必填：清晰、描述性标题
description: "页面描述"     # 必填：简要摘要
date: YYYY-MM-DD           # 必填：创建日期
lastmod: YYYY-MM-DD        # 必填：最后修改日期
categories: ["类别"]        # 必填：主类别
tags: ["标签1", "标签2"]    # 必填：相关标签
weight: 10                 # 必填：导航权重
---

选填字段：

---
# ... 必填字段 ...
author: "作者姓名"           # 选填：内容作者
draft: false                # 选填：草稿状态
toc: true                   # 选填：目录显示
review_date: YYYY-MM-DD     # 选填：下次评审日期
maintenance_priority: medium # 选填：高、中、低
content_status: current     # 选填：当前、需评审、过时
---

质量保障

发布前检查清单

内容审核：

  • 信息准确且最新
  • 语言清晰，适合受众
  • 示例可按描述运行
  • 链接有效且相关
  • 图片有 alt 文本且已优化

技术审核：

  • 代码示例已测试可用
  • 步骤逐一验证
  • 配置示例有效
  • 交叉引用准确

格式审核：

  • Front Matter 完整且正确
  • Markdown 格式统一
  • 标题层级合理
  • 列表和表格格式正确

验证工具

自动验证：

# 运行全面验证
npm run validate-docs

# 检查特定项
npm run docs-health          # 健康检查
npm run docs-freshness       # 内容新鲜度
npm run link-check           # 链接验证

手动测试：

  • 按文档流程操作
  • 在干净环境测试代码示例
  • 验证跨平台兼容性
  • 检查移动端响应性

维护职责

内容归属

主要作者：

  • 负责内容及时更新
  • 关注用户反馈和问题
  • 功能变更时及时修订内容
  • 定期参与内容评审

文档团队：

  • 协调整体文档策略
  • 维护风格指南和模板
  • 审核贡献内容的一致性
  • 管理文档基础设施

更新触发条件

需立即更新：

  • 新功能发布
  • 重大变更
  • 安全更新
  • 影响文档行为的 bug 修复

定期更新：

  • 每季度内容新鲜度评审
  • 每年全面审计
  • 定期链接验证
  • 截图和示例更新

审核流程

小幅更新（错别字、小修正）：

  1. 直接修改
  2. 更新 lastmod 日期
  3. 运行验证工具
  4. 用描述性信息提交

重大更新（新内容、结构调整）：

  1. 创建功能分支
  2. 全面修改
  3. 运行完整验证
  4. 提交详细拉取请求
  5. 响应评审反馈
  6. 评审通过后合并

关键更新（重大变更、安全）：

  1. 按紧急流程操作
  2. 与相关方协调
  3. 需多位评审通过
  4. 部署后密切监控

最佳实践

以用户为中心

了解你的受众：

  • 理解用户目标和痛点
  • 提供适当细节
  • 包含实际案例
  • 考虑不同技能和背景

任务导向组织：

  • 按用户任务组织内容
  • 为不同场景提供清晰入口
  • 复杂主题分步展开
  • 提供快速参考材料

可访问性与包容性

无障碍写作：

  • 使用简明语言
  • 图片加替代文本
  • 用合适标题结构化内容
  • 音视频内容附文字稿

包容性语言：

  • 尽量使用性别中性表达
  • 避免文化假设
  • 定义技术术语和缩写
  • 考虑非母语用户

SEO 与可发现性

搜索优化：

  • 使用描述性标题和小节
  • 自然融入相关关键词
  • 提供全面 meta 描述
  • 用合适标记结构化内容

内部链接：

  • 合理链接相关内容
  • 使用描述性锚文本
  • 构建逻辑内容路径
  • 保持链接健康

工具与资源

文档工具

写作与编辑：

  • 支持实时预览的 Markdown 编辑器
  • 语法和拼写检查工具
  • 链接验证工具
  • 图片优化工具

测试与验证：

  • 自动化文档测试
  • 链接检查服务
  • 无障碍测试工具
  • 跨浏览器测试

风格资源

参考材料：

  • 项目风格指南
  • Markdown 语法参考
  • Hugo 官方文档
  • 无障碍指南

模板与示例：

  • 内容类型模板
  • 示例文档页面
  • 代码片段库
  • 图片与媒体规范

获取帮助

支持渠道

文档问题：

  • 创建 issue 报告文档 bug
  • 用讨论区交流一般问题
  • 联系文档团队寻求指导
  • 参与文档评审

技术支持：

  • 开发环境搭建问题
  • 工具配置疑问
  • 构建与部署问题
  • 集成相关挑战

参与指南维护

本指南会随项目发展不断完善：

  • 通过 issue 或拉取请求建议改进
  • 反馈有效或需澄清的内容
  • 贡献示例和最佳实践
  • 协助保持内容准确和相关性

结语

高质量文档对项目成功至关重要。遵循本指南，贡献者可帮助打造：

  • 实用 —— 帮助用户达成目标
  • 准确 —— 信息正确且及时
  • 可访问 —— 所有人都能获取
  • 易维护 —— 便于持续更新

感谢你为文档贡献力量！你的付出让项目文档更好，惠及所有用户。

如对本指南有疑问或建议，请创建 issue 或联系文档团队。