Help us learn about your current experience with the documentation. Take the survey.

自动化页面

GitLab 文档中的大多数页面都是手动用 Markdown 编写的。 但是，有些页面是通过自动化流程创建的。

GitLab 文档中存在两种主要的自动化类别：

  • 通过使用标准流程和结构化数据（例如 YAML 或 JSON 文件）生成的内容。
  • 通过任何其他方式生成的内容。

自动化有助于保持一致性和速度。但是，以非标准方式自动化的内容会导致以下问题：

  • 前端变更。
  • 网站故障排除和维护。
  • 贡献者体验。

理想情况下，任何自动化都应该以标准方式进行，这有助于减轻一些缺点。

从结构化数据生成的页面

docs 站点的某些功能使用结构化数据：

  • 分层全局导航（YAML）
  • 调查横幅（YAML）
  • 徽章（YAML）
  • 首页内容列表（YAML）
  • 重定向（YAML）
  • 版本菜单（JSON）

其他方式生成的页面

其他页面是通过使用非标准流程生成的。这些页面通常使用跨多个仓库编码的解决方案。

Page Details Owner
All feature flags in GitLab Generated during docs build Technical Writing
GitLab Runner feature flags Page source Runner
GitLab Runner Kubernetes API settings Generated with mage Runner
Deprecations and removals by version Update the deprecations and removals documentation
Breaking change windows Update the breaking change windows documentation
GraphQL API resources GraphQL API style guide Import and Integrate
REST API OpenAPI V2 documentation Documenting REST API resources Import and Integrate
Audit event types Audit event development guidelines Compliance
Available custom role permissions Generated by Rake task Authorization
CI/CD Job token fine-grained permissions Generated by Rake task Authorization
Application settings analysis Generated by Ruby script
DAST vulnerability check documentation (Example) How to generate the Markdown Dynamic Analysis
The docs homepage Technical Writing

提出自动化请求

如果您想在 docs 站点上自动化一个页面：

  1. 查看 issue 246 并考虑在那里添加反馈。
  2. 如果该问题没有描述您的需求，请联系 docs 站点后端的 DRI。

因为自动化会增加额外的复杂性和支持负担，所以我们 会根据具体情况逐一审查。

记录自动化

如果您确实添加了自动化，必须记录：

  • 包含的文件列表。
  • .gitlab-ci.yml 更新和任何流水线要求。
  • 故障排除所需的步骤。

其他 GitLab 团队成员应该能够轻松找到有关如何维护自动化的信息。 您应该广泛宣布变更，至少包括：

  • 在 Slack 的 #whats-happening-at-gitlab 频道。
  • 在 Technical Writer 团队会议议程中。