Automated pages

Most pages in the GitLab documentation are written manually in Markdown. However, some pages are created by automated processes.

Two primary categories of automation exist in the GitLab documentation:

  • Content that is generated by using a standard process and structured data (for example, YAML or JSON files).
  • Content that is generated by any other means.

Automation helps with consistency and speed. But content that is automated in a non-standard way causes difficulty with:

  • Frontend changes.
  • Site troubleshooting and maintenance.
  • The contributor experience.

Ideally, any automation should be done in a standard way, which helps alleviate some of the downsides.

Pages generated from structured data

Some functionality on the docs site uses structured data:

  • Hierarchical global navigation (YAML)
  • Survey banner (YAML)
  • Badges (YAML)
  • Homepage content lists (YAML)
  • Redirects (YAML)
  • Versions menu (JSON)

Pages generated otherwise

Other pages are generated by using non-standard processes. These pages often use solutions that are coded across multiple repositories.

Page Details Owner
All feature flags in GitLab Generated during docs build Technical Writing
GitLab Runner feature flags Page source 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
Audit event types Audit event development guidelines Compliance
Available custom role permissions Generated by Rake task Authorization
DAST vulnerability check documentation (Example) How to generate the Markdown Dynamic Analysis
The docs homepage   Technical Writing

Make an automation request

If you want to automate a page on the docs site:

  1. Review issue 823 and consider adding feedback there.
  2. If that issue does not describe what you need, contact the DRI for the docs site backend.

Because automation adds extra complexity and a support burden, we review it on a case-by-case basis.

Document the automation

If you do add automation, you must document:

  • The list of files that are included.
  • The .gitlab-ci.yml updates and any pipeline requirements.
  • The steps needed to troubleshoot.

Other GitLab team members should be able to easily find information about how to maintain the automation. You should announce the change widely, including, at a minimum:

  • In Slack, in #whats-happening-at-gitlab.
  • In the Technical Writer team meeting agenda.