ContextQMD
Back to Gitlabhq

Metadata

doc/development/documentation/metadata.md

18.11.28.1 KB
Original Source

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.

Stage and group metadata

Each page should have metadata related to the stage and group it belongs to, an information block, and the page title. For example:

yaml
---
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.

Exceptions

Documents in the /development directory get this metadata:

yaml
---
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:

yaml
---
stage: Solutions Architecture
group: Solutions Architecture
info: This page is owned by the Solutions Architecture team.
title: Example page title
---

Unassigned pages

Documents with no clear group owner are considered unassigned and get this metadata:

yaml
---
stage: none
group: unassigned
info: For assistance with this Style Guide page, see <https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects>.
title: Example page title
---

You can add additional information to stage and group, provided the metadata remains valid YAML.

Title metadata

The title metadata:

  • Generates the H1 (level one heading) at the top of the rendered page.
  • Can be used to generate automated page listings.
  • Replaces Markdown H1 headings (like # Page title).

Description metadata

The description tag:

  • Is used to populate text on the documentation home page.
  • Is shown in social media previews.
  • Can be used in search result snippets.
  • Is shown when the page is included in a cards shortcode.

For the top-level pages, like Use GitLab and one level underneath, the description should be a short sentence that starts with an active verb. The description should give users a clear idea of the information they will find on the page and the value of visiting the page.

For other pages, use a short description of what the page is about:

Avoid pages being added to global navigation

If 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:

yaml
ignore_in_report: true

When this metadata is set on a page:

  • The pages_not_in_nav.cjs script ignores the page when processing the documentation.
  • Technical writers doing the Technical Writing team's monthly tasks aren't prompted to add the page to the global navigation.

Indicate GitLab Dedicated support

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:

yaml
gitlab_dedicated: no

When a page applies to GitLab Dedicated, use:

yaml
gitlab_dedicated: yes

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.

Indicate lack of product availability details

On pages that purposely do not have availability details, add this metadata to the top of the page:

yaml
availability_details: no

Additional metadata

The following metadata is optional and is not actively maintained.

  • feedback: Set to false to exclude the Was this page helpful? feedback widget.
  • 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.
  • toc: Set to false to exclude the right navigation.

Batch updates for TW metadata

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:

  • The list of users in the Approvers section.
  • The technical writer that the GitLab Bot pings for community contributions.

You can use a Rake task to update the CODEOWNERS file.

Update the 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:

  1. Checks all files in the doc directory.
  2. Reads the value of group from the metadata. Any value in group that isn't known to the Rake task causes the page to be treated as not assigned to a technical writer.
  3. Uses the information in the codeowners.rake file to populate the CODEOWNERS file.

To update the CODEOWNERS file:

  1. 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.
  2. Update the codeowners.rake file with the changes.
  3. Go to the root of the gitlab repository.
  4. Run the Rake task with this command: bundle exec rake tw:codeowners
  5. Review the changes in the CODEOWNERS file.
  6. Add and commit all your changes and push your branch up to origin.
  7. Create a merge request and assign it 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.

    ruby
    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:

      ruby
      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:

    ruby
    # CodeOwnerRule.new('Group Name', ''),