Each documentation Markdown page contains YAML front matter. All values in the metadata are treated as strings and are used for the documentation website only.
Each page should have metadata related to the stage and group it belongs to, an information block, and the page title. For example:
---
stage: Example Stage
group: Example Group
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
title: Example page title
---To populate the metadata, include this information:
stage: The Stage that the majority of the page’s content belongs to.group: The Group that the majority of the page’s content belongs to.info: How to find the Technical Writer associated with the page’s stage and group.title: The page title that appears as the H1 (level one heading) at the top of the page.Documents in the /development directory get this metadata:
---
stage: Example Stage
group: Example Group
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/development/development_processes/#development-guidelines-review.
title: Example page title
---Documents in the /solutions directory get this metadata:
---
stage: Solutions Architecture
group: Solutions Architecture
info: This page is owned by the Solutions Architecture team.
title: Example page title
---The title metadata:
# Page title).The description tag:
cards shortcode.For the top-level pages, like Use GitLab and one level underneath, the descriptions are lists of nouns. For example, for Set up your organization, the description is Users, groups, namespaces, SSH keys.
For other pages, descriptions are not actively maintained. However, if you want to add one, use a short description of what the page is about. See the Google Best practices for creating quality meta descriptions for tips.
Avoid pages being added to global navigationIf a specific page shouldn’t be added to the global navigation (have an entry added to navigation.yaml, add the following to the page’s metadata:
When this metadata is set on a page:
pages_not_in_nav.cjs script ignores the page when processing the documentation.The gitlab_dedicated metadata indicates whether a documentation page applies to GitLab Dedicated.
Add this field to documentation pages when GitLab Dedicated availability status has been confirmed with the product team. This metadata should complement, not replace, the information from the Offering details.
For example, usually pages that apply to GitLab Self-Managed apply to GitLab Dedicated. Use this metadata when they don’t:
When a page applies to GitLab Dedicated, use:
For pages with partial availability on GitLab Dedicated, use gitlab_dedicated: yes and update the product availability details for any topics that don’t apply to GitLab Dedicated.
On pages that purposely do not have availability details, add this metadata to the top of the page:
The following metadata is optional and is not actively maintained.
feedback: Set to false to not include the “Help & Feedback” footer.noindex: Set to true to prevent the page from being indexed by search engines.redirect_to: Used to control redirects. For more information, see Redirects in GitLab documentation.searchbar: Set to false to not include the search bar in the page header.toc: Set to false to not include the “On this page” navigation.The CODEOWNERS file contains a list of files and the associated technical writers.
When a merge request contains documentation, the information in the CODEOWNERS file determines:
You can use a Rake task to update the CODEOWNERS file.
CODEOWNERS file
When groups or TW assignments change, you must update the CODEOWNERS file. To do this, you run the codeowners.rake Rake task. This task checks all files in the doc directory, reads the metadata, and uses the information in the codeowners.rake file to populate the CODEOWNERS file.
To update the CODEOWNERS file:
Update the stage and group metadata for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR.
Update the codeowners.rake file with the changes.
Go to the root of the gitlab repository.
Run the Rake task with this command: bundle exec rake tw:codeowners
Review the changes in the CODEOWNERS file.
Add and commit all your changes and push your branch up to origin.
Create a merge request and add the ~"pipeline:skip-undercoverage" label to it.
Because this merge request modifies a code file, GitLab Bot runs a tier-3 pipeline when the MR is approved. The pipeline fails at rspec:undercoverage because we don’t have tests for codeowners.rake. Add the label to skip the test coverage check.
Assign the merge request to a technical writing manager for review.
When you update the codeowners.rake file:
To specify multiple writers for a single group, use a space between writer names. Files are assigned to both writers.
CodeOwnerRule.new('Group Name', '@writer1 @writer2'),To assign different writers in a group to documentation in different directories, use the path parameter to specify a directory:
CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }),In this example, writer1 is a code owner for files related to this group that are in /doc/user. For everything else, writer2 is made code owner. For an example, see MR 127903.
For a group that does not have an assigned writer, include the group name in the file and comment out the line:
# CodeOwnerRule.new('Group Name', ''),RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4