doc/development/documentation/styleguide/_index.md
This document defines the standards for GitLab documentation, including grammar, formatting, and more. For guidelines on specific words, see the word list.
The GitLab brand guidelines define the voice used by the larger organization.
Building on that guidance, the voice in the GitLab documentation strives to be concise, direct, and precise. The goal is to provide information that's easy to search and scan.
The voice in the documentation should be conversational but brief, friendly but succinct.
The GitLab documentation is the SSoT for all product information related to implementation, use, and troubleshooting. The documentation evolves continuously. It is updated with new products and features, and with improvements for clarity, accuracy, and completeness.
This policy:
GitLab uses topic types to organize the product documentation.
Topic types help users digest information more quickly. They also help address these issues:
The product documentation should be a complete and trusted resource.
The more we reflexively add information to the documentation, the more the documentation helps others efficiently accomplish tasks and solve problems.
We follow guidelines that help us write for a global audience.
The GitLab voice dictates that we write clearly and directly with translation in mind. Our style guide, word list, and Vale rules ensure consistency in the documentation.
When documentation is translated into other languages, the meaning of each word must be clear. The increasing use of machine translation, GitLab Duo Chat, and other AI tools means that consistency is even more important.
The following rules can help documentation be translated more efficiently.
Avoid:
Use:
Also, keep the following guidance in mind:
All GitLab documentation is written in Markdown.
The documentation website uses the Hugo static site generator with its default Markdown engine, Goldmark.
Markdown formatting is tested by using markdownlint and Vale.
Hard-coded HTML is valid, although it's discouraged for a few reasons:
/help.HTML is permitted if:
Any links created with HTML <a> tags must use absolute URLs as their
href attributes. Unlike regular links, do not use relative links to
Markdown files, as Hugo can only process and replace Markdown-formatted links.
If you have an idea or request for a new element that would be useful on the Docs site, submit a feature request.
Each documentation page must include a title attribute in its metadata.
The title becomes the H1 element when rendered to HTML.
Do not add an H1 heading in Markdown because there can be only one for each page.
# characters
in front of the topic title.H5 (#####). If you need more than five heading levels, move the topics to a new page instead.
Heading levels greater than H4 do not display in the right sidebar navigation.## > ####.To define terms or differentiate between options, use description lists. For a list of UI elements, use a regular list instead of a description list.
Do not mix description lists with other styles.
Term 1
: Definition of Term 1
Term 2
: Definition of Term 2 is much longer, but we can use
multiple lines.
These lists render like this:
Term 1 : Definition of Term 1
Term 2 : Definition of Term 2 is much longer, but we can use multiple lines.
Shortcodes are snippets of template code that we can include in our Markdown content to display non-standard elements on a page, such as availability details or tabs.
GitLab documentation uses the following shortcodes:
GitLab documentation should be clear and easy to understand.
British.yml.)In most cases, text is easier to understand and to translate if you use active voice instead of passive.
For example, use:
Instead of:
Sometimes, GitLab as the subject can be awkward. For example, GitLab exports the report.
In this case, use passive voice instead. For example, The report is exported.
Focus on the functionality and benefits that GitLab brings to customer, rather than what GitLab has created.
For example, use:
Instead of:
Words that indicate you are not writing from a customer perspective are allow and enable. Try instead to use you and to speak directly to the user.
Product documentation should be focused on providing clear, concise information, without the addition of sales or marketing text.
Instead, focus on facts and achievable goals. Be specific. For example:
Avoid writing about the document itself. For example, do not use:
These phrases slow the user down. Instead, get right to the point. For example, instead of:
Use:
Tested in SelfReferential.yml.
As a company, we tend toward lowercase.
Use sentence case for topic titles. For example:
# Use variables to configure pipelines## Use the To-Do ListWhen referring to specific user interface text, like a button label, page, tab, or menu item, use the same capitalization that's displayed in the user interface.
The only exception is text that's all uppercase (for example, RECENT FLOWS).
In this case, use sentence case.
If you think the user interface text contains style mistakes, create an issue or an MR to propose a change to the user interface text.
Feature names should be lowercase.
However, in a few rare cases, features can be title case. These exceptions are:
If the term is not in the word list, ask a GitLab Technical Writer for advice. For assistance naming a feature and ensuring it meets GitLab standards, see the handbook.
Do not match the capitalization of terms or phrases on the Features page
or features.yml
by default.
Capitalize names of:
Follow the capitalization style listed at the authoritative source for the entity, which might use non-standard case styles. For example: GitLab and npm.
Do not include real usernames or email addresses in the documentation.
For text:
Sidney Jones, Zhang Wei, or Alex Garcia.example.com.For screenshots:
Temporarily edit the page before you take the screenshot:
Alternatively, create example accounts in a test environment, and take the screenshot there.
If you can't reproduce the environment, blur the user data by using an image editing tool like Preview on macOS.
When including sample URLs in the documentation, use:
example.com when the domain name is generic.gitlab.example.com when referring only to GitLab Self-Managed.
Use gitlab.com for GitLab.com.Do not use real tokens in the documentation.
Use these fake tokens as examples:
| Token type | Token value |
|---|---|
| Personal access token | <your_access_token> |
| Application ID | 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 |
| Application secret | 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df |
| CI/CD variable | Li8j-mLUVA3eZYjPfd_H |
| Project runner token | yrnZW46BrtBFqM7xDzE7dddd |
| Instance runner token | 6Vk7ZsosqQyfreAxXTZr |
| Trigger token | be20d8dcc028677c931e04f3871a9b |
| Webhook secret token | 6XhDroRcYPM5by_h-HLY |
| Health check token | Tu7BgjR9qeZTEyRzGG2P |
Contractions are encouraged, and can create a friendly and informal tone, especially in tutorials, instructional documentation, and user interfaces.
Some contractions, however, should be avoided:
<!-- vale gitlab_base.Possessive = NO -->| Do not use a contraction | Example | Use instead |
|---|---|---|
| With a proper noun and a verb | Terraform's a helpful tool. | Terraform is a helpful tool. |
| To emphasize a negative | Don't install X with Y. | Do not install X with Y. |
| In reference documentation | Don't set a limit. | Do not set a limit. |
| In error messages | Requests to localhost aren't allowed. | Requests to localhost are not allowed. |
Do not use possessives ('s) for proper nouns, like organization or product names.
For example, instead of Docker's CLI, use the Docker CLI.
For details, see the Google documentation style guide.
Use prepositions at the end of the sentence when needed. Dangling or stranded prepositions are fine. For example:
These constructions are more casual than the alternatives:
If you use an acronym, spell it out on first use on a page. Do not spell it out more than once on a page.
YAML files, not YAMLs. If you must make an acronym plural, do not use an apostrophe. For example, use APIs, not API's.For numbers in text, spell out zero through nine and use numbers for 10 and greater. For more information, see the Microsoft Style Guide.
For numbers in the UI, see Pajamas.
Use the month day, year format for dates, and use AM and PM for times.
For example:
January 3, 2026 at 10:30 AM
For additional details, see the Microsoft Style Guide.
For dates and times in the UI, see Pajamas.
Insert an empty line for new paragraphs.
Insert an empty line between different markups (for example, after every paragraph, heading, and list). Example:
## Heading
Paragraph.
- List item 1
- List item 2
To make the source content easy to read, and to compare diffs, follow these best practices.
To embed comments in Markdown, use standard HTML comments that are not rendered when published. Example:
<!-- This is a comment that is not rendered -->
Use HTML comments to make notes for authors who need to know details about how to maintain the page.
For example: This table is autogenerated, edit 'path/to/file.rb' and run 'script.sh' to update the table.
Do not use HTML comments to hide documentation. For details see, Delete instead of hiding documentation.
Follow these guidelines for punctuation.
For punctuation in the UI, see Pajamas.
<!-- vale gitlab_base.Repetition = NO -->OxfordComma.yml.)When spacing content:
SentenceSpacing.yml.)lint-doc.sh.)Do not use these punctuation characters:
; (semicolon): Use two sentences instead.– (en dash) or — (em dash): Use separate sentences, or commas, instead.“ ” ‘ ’: Double or single typographer's ("curly") quotation marks. Use straight quotes instead. (Tested in NonStandardQuotes.yml.)In a code block, you might want to provide a command or configuration that uses specific values.
In these cases, use < and >
to call out where a reader must replace text with their own value.
For example:
cp <your_source_directory> <your_destination_directory>
If the placeholder is not in a code block, use < and > and wrap the placeholder
in a single backtick. For example:
Select **Grant admin consent for `<application_name>`**.
Follow the Microsoft guidance for quotation marks.
Try to avoid quotation marks for user input and instead, use backticks.
When formatting text, use:
<kbd> for keyboard commands.Use bold for:
Do not use bold for keywords or emphasis.
UI elements include:
For example:
To make text bold, wrap it with double asterisks (**). For example:
1. Select **Cancel**.
When you use bold format for UI elements, place any punctuation outside the bold tag.
This rule includes periods, commas, colons, and right-angle brackets (>).
The punctuation is part of the sentence structure rather than the UI element that you're emphasizing.
Include punctuation in the bold tag when it's part of the UI element itself.
For example:
**Start a review**: This is a description of the button that starts a review.Select **Overview** > **Users**.Inline code is text that's wrapped in single backticks (`). For example:
In the **Name** text box, enter `test`.
Use inline code for:
true, false, Job succeeded, and similar..gitlab-ci.yml, --version, or rules:.POST).404 File Not Found) and abbreviated (404).<sup>. Include the angle brackets.For example:
test.rules: CI/CD keyword to control when to add jobs to a pipeline.DELETE request to delete the runner. Send a POST request to create one.Job succeeded when complete.Code blocks separate code text from regular text, and can be copy-pasted by users.
Use code blocks for:
To add a code block, add triple backticks (```) above and below the text,
with a syntax name at the top for proper syntax highlighting. For example:
```markdown
This is a code block that uses Markdown to demonstrate **bold** and `backticks`.
```
When you use code blocks:
plaintext if no better option is available.````) when the code block contains another (nested) code block
which has triple backticks already. The example above uses quadruple backticks internally
to illustrate the code block format.To represent missing information in a code block, use a comment or an ellipsis. For example:
# Removed for readability// ...When writing about keystroke presses:
<kbd> tag.<kbd> tags in key combinations.Alt (Vale rule: SubstitutionWarning.yml).Shift, Command, Delete.↑, ↓, ←, and → for arrows.For example:
To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.
This example renders as:
To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.
Avoid italics for emphasis in product documentation. Instead, write content that is clear enough that emphasis is not needed. GitLab and https://docs.gitlab.com use a sans-serif font, but italic text does not stand out in a page using sans-serif.
Use lists to present information in a format that is easier to scan.
Make all items in the list parallel. For example, do not start some items with nouns and others with verbs.
Start all items with a capital letter.
Give all items the same punctuation.
Do not use a period if the item is not a complete sentence.
Use a period after every complete sentence, or where the list item forms a complete sentence when combined with the introductory phrase. Do not use semicolons or commas.
Add a colon (:) after the introductory phrase.
For example:
The basket contains these fruits:
- Bananas
- Apples
Do not use bold formatting to define keywords or concepts in a list. Use bold for UI element labels only. For example:
**Start a review**: This is a description of the button that starts a review.Offline environments: This is a description of offline environments.For keywords and concepts, consider a reference topic or description list for alternative formatting.
Avoid using list items to complete an introductory phrase. This format can be difficult to localize into languages that use different sentence structures. For example, use:
You can get the license key in the following ways:
- Copy the license key from the email.
- Download the file.
Instead of:
You can get the license key by:
- Copying it from the email.
- Downloading the file.
Use ordered lists for a sequence of steps. For example:
Follow these steps to do something.
1. First, do the first step.
1. Then, do the next step.
1. Finally, do the last step.
Use an unordered lists when the steps do not need to be completed in order. For example:
These things are imported:
- Thing 1
- Thing 2
- Thing 3
-) for unordered lists instead of asterisks (*).1.. When rendered, the list items
are sequential.The following items can be nested under a list item, so they render with the same indentation as the list item:
Nested items should always align with the first character of the list
item. For unordered lists (using -), use two spaces for each level of
indentation:
- Unordered list item 1
A line nested that uses 2 spaces to align with the `U` above.
- Unordered list item 2
> A quote block that will nest
> inside list item 2.
- Unordered list item 3
```plaintext
a code block that nests inside list item 3
```
- Unordered list item 4
For ordered lists, use three spaces for each level of indentation:
1. Ordered list item 1
A line nested that uses 3 spaces to align with the `O` above.
You can nest lists in other lists.
1. Ordered list item one.
1. Ordered list item two.
- Nested unordered list item one.
- Nested unordered list item two.
1. Ordered list item three.
- Unordered list item one.
- Unordered list item two.
1. Nested ordered list item one.
1. Nested ordered list item two.
- Unordered list item three.
Use the guide shortcode to create a stylized ordered list of steps. You can nest other shortcodes (like alerts) in guides. However, do this sparingly as the rendered styling can make the content difficult to scan.
Do not use a guide in a guide.
To create a guide, follow this example:
{{</* guide */>}}
1. Guide item with text.
An item with text only.
1. Guide item with alert.
This is an item with an alert.
> [!note]
> This is a note.
{{</* /guide */>}}
This code renders on the GitLab documentation site as:
{{< guide >}}
Guide item with text.
An item with text only.
Guide item with alert.
An item with an alert.
[!note] This is a note.
{{< /guide >}}
Guide styling renders only on the GitLab documentation site (https://docs.gitlab.com).
In the GitLab product help, a guide appears as a regular ordered list of items.
Use guides for tutorials only. For most tasks, use an ordered list.
Tables should be used to describe complex information in a straightforward manner. In many cases, an unordered list is sufficient to describe a list of items with a single description for each item. But, if you have data that's best described by a matrix, tables are the best choice.
To keep tables accessible and scannable, tables should not have any empty cells. If no otherwise meaningful value for a cell exists, consider entering N/A for 'not applicable' or None.
To make tables easier to maintain:
If the table has a Description column, make it the right-most column if possible.
Add additional spaces to make the column widths consistent. For example:
| Parameter | Default | Requirements |
|-----------|--------------|--------------|
| `param1` | `true` | A and B. |
| `param2` | `gitlab.com` | None |
Skip the additional spaces in the rightmost column for tables that are very wide. For example:
| Setting | Default | Description |
|-----------|---------|-------------|
| Setting 1 | `1000` | A short description. |
| Setting 2 | `2000` | A long description that would make the table too wide and add too much whitespace if every cell in this column was aligned. |
| Setting 3 | `0` | Another short description. |
The header (first) row and the delimiter (second) row of the table should be the same length.
Do not use shortened delimiter rows like |-|-|-| or |--|--|.
If a large table does not auto-format well, you can skip the auto-format but:
| characters and cell contents.
For example | Cell 1 | Cell 2 |, not |Cell1|Cell2|.You can use Hugo class attributes to make a table condensed or expandable. To avoid introducing linting errors in a table, test the table locally with all rules enabled.
Hugo class attributes only render on the GitLab documentation site (https://docs.gitlab.com).
A condensed table is scrollable vertically and horizontally, as necessary, and has a restricted height.
By default, wide tables that do not fit on the page are condensed. Long tables are not condensed. You can optionally add
the condensed class attribute to reduce the space the table takes up on a page.
| Parameter | Default | Requirements |
|-----------|--------------|--------------|
| `param1` | `true` | A and B. |
| `param2` | `gitlab.com` | None |
{.condensed}
or
| Parameter | Default | Requirements |
|-----------|--------------|--------------|
| `param1` | `true` | A and B. |
| `param2` | `gitlab.com` | None |
{class="condensed"}
Expandable tables have an Expand table button that, when selected, opens the table in a dialog.
To create an expandable table, use the expandable class attribute.
To make a table both condensed and expandable, use both attributes. For example:
{.condensed .expandable}
Or:
{class="condensed expandable"}
To ensure consistent table formatting across all Markdown files, consider formatting your tables with the VS Code Markdown Table Formatter. To configure this extension to follow the guidelines above, turn on the Follow header row length setting. To turn on the setting:
In the UI:
Limit Last Column Length.In your VS Code settings.json, add a new line with:
{
"markdown-table-formatter.limitLastColumnLength": "Follow header row length"
}
To format a table with this extension, select the entire table, right-click the selection, and select Format Selection With. Select Markdown Table Formatter in the VS Code Command Palette.
If you use Sublime Text, try the Markdown Table Formatter plugin, but it does not have a Follow header row length setting.
When you add or edit rows in an existing table, some rows might not be aligned anymore. Don't realign the entire table if only changing a few rows. If you realign the columns to account for the width, the diff becomes difficult to read, because the entire table shows as modified.
Markdown tables naturally fall out of alignment over time, but still render correctly
on docs.gitlab.com. The technical writing team can realign cells the next time
the page is refactored.
Use sentence case for table headers. For example, Keyword value or Project name.
When creating tables of lists of features (such as the features available to each role on the Permissions page), use these shortcodes:
| Option | Markdown | Renders | Notes |
|---|---|---|---|
| No | {{</* no */>}} | {{< no >}} | Renders a hidden span for screen readers: <span class="gl-sr-only">no</span> |
| Yes | {{</* yes */>}} | {{< yes >}} | Renders a visible checkmark icon and a hidden span for screen readers: <span class="gl-sr-only">yes</span> |
Do not use these shortcodes in API documentation or inline text. For API documentation, follow the API topic template.
Use footnotes below tables only when you cannot include the content in the table itself. For example, use footnotes when you must:
In the table, use the HTML superscript tag <sup> for each footnote.
Put the tag at the end of the sentence. Leave one space between the sentence and the tag.
For example:
| App name | Description |
|:---------|:------------|
| App A | Description text. <sup>1</sup> |
| App B | Description text. <sup>2</sup> |
When you add a footnote, do not re-sort the existing tags in the table.
For the footnotes below the table, use **Footnotes**: followed by an ordered list.
For example:
**Footnotes**:
1. This is the first footnote.
1. This is the second footnote.
The table and footnotes would render as follows:
| App name | Description |
|---|---|
| App A | Description text. <sup>1</sup> |
| App B | Description text. <sup>2</sup> |
Footnotes:
If you have five or more footnotes that you cannot include in the table itself,
use consecutive numbers for the list items.
If you use consecutive numbers, you must disable Markdown rule 029:
**Footnotes**:
<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix -->
<!-- markdownlint-disable MD029 -->
1. This is the first footnote.
2. This is the second footnote.
3. This is the third footnote.
4. This is the fourth footnote.
5. This is the fifth footnote.
<!-- markdownlint-enable MD029 -->
Links are an important way to help readers find what they need.
However, most content is found by searching, and you should avoid putting too many links on any page. Too many links can hinder readability.
Use inline links instead of reference links. Inline links are easier to parse
and edit.
(Vale rule: ReferenceLinks.yml)
Do:
For more information, see [merge requests](path/to/merge_requests.md)
Don't:
For more information, see [merge requests][1].
[1]: path/to/merge_requests.md
To link to another documentation (.md) file in the same repository:
[GitLab.com settings](../user/gitlab_com/_index.md).MultiLineLinks.yml).[!note] In the GitLab repository, do not link to the
/developmentdirectory from any other directory.
To link to a file outside of the documentation files, for example to link from development documentation to a specific code file:
[`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/views/help/show.html.haml)[`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/6d01aa9f1cfcbdfa88edf9d003bd073f1a6fff1d/app/views/help/show.html.haml)To link to a page in a different repository, use a full URL.
For example, to link from a page in the GitLab repository to the Charts repository,
use a URL like [GitLab Charts documentation](https://docs.gitlab.com/charts/).
Each topic title has an anchor link. For example, a topic with the title
## This is an example has the anchor #this-is-an-example.
When you change topic title text, the anchor link changes. To avoid broken links:
When you change a topic title, the anchor link changes. If other documentation pages or code files link to this anchor, pipeline jobs could fail.
Consider running the link checks locally before pushing your changes to prevent failing pipelines.
Follow these guidelines for link text.
For writing link text in the UI, see Pajamas.
Use text that follows one of these patterns:
For more information, see [link text](link.md).To [DO THIS THING], see [link text](link.md)For example:
For more information, see [merge requests](link.md).To create a review app, see [review apps](link.md).To expand on this text, use phrases like
For more information about this feature, see...
Do not use the following constructions:
Learn more about...To read more....For more information, see the [Merge requests](link.md) page.For more information, see the [Merge requests](link.md) documentation.hereUse descriptive text for links, rather than words like here or this page.
For the name of a topic or page, use lowercase.
You don't have to match the text to the topic or page name exactly.
Edit the text to be descriptive and fit the guidelines.
Do:
For more information, see [merge requests](link.md).For more information, see [roles and permissions](link.md).For more information, see [how to configure common settings](link.md).Don't:
For more information, see [this page](link.md).For more information, go [here](link.md).For more information, see [this documentation](link.md).When linking to an issue, include the issue number in the link. For example:
For more information, see [issue 12345](link.md).Do not use the pound sign (issue #12345).
When linking to API documentation, use lowercase. For example:
To import your GitHub repository, see the [import API](link.md).Do not capitalize the first letter to match the page title. For example, do not use:
To import your GitHub repository, see the [Import API](link.md).When possible, avoid links to external documentation. These links can become outdated and are difficult to maintain.
Sometimes links are required. They might clarify troubleshooting steps or help prevent duplication of content. Sometimes they are more precise and will be maintained more actively.
For each external link you add, weigh the customer benefit with the maintenance difficulties.
Limit links to the handbook. Some links are unavoidable, like licensing terms, data usage and access policies, testing agreements, and terms and conditions.
Don't link directly to:
These links fail for:
If you must use one of these links:
Examples:
GitLab team members can view more information in this confidential issue:
`https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>`
GitLab team members can view more information in this internal handbook page:
`https://internal.gitlab.com/handbook/<link>`
Users with the Maintainer role for the project can use the pipeline editor:
`https://gitlab.com/gitlab-org/gitlab/-/ci/editor`
When linking to specific lines in a file, link to a commit instead of to the branch. Lines of code change over time. Linking to a line by using the commit link ensures the user lands on the line you're referring to. The Permalink dropdown item in the ellipsis menu, displayed when viewing a file in a project, provides a link to the most recent commit of that file.
[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).If that linked expression has changed line numbers due to additional commits, you can still search the file for that query. In this case, update the document to ensure it links to the most recent version of the file.
When documenting how to navigate the GitLab UI:
In the GitLab UI, use the following names:
the **Explore** menu or the **Your work** sidebar. Instead, use the left sidebar.The right sidebar is the navigation sidebar on the right of the user interface, specific to an open issue, merge request, or epic.
With the exception of GitLab Duo, use lowercase for all above terms.
All UI elements should be bold. The > in the navigation path should not be bold.
Additional guidance for individual UI elements is in the word list.
To be consistent, use these examples to write navigation steps in a task topic. Although alternative steps might exist, including items pinned by default, use these steps instead.
To open project settings:
1. In the top bar, select **Search or go to** and find your project.
1. Select **Settings** > **CI/CD**.
1. Expand **General pipelines**.
To open group settings:
1. In the top bar, select **Search or go to** and find your group.
1. Select **Settings** > **CI/CD**.
1. Expand **General pipelines**.
To open settings for a top-level group:
1. In the top bar, select **Search or go to** and find your group.
This group must be at the top level.
1. Select **Settings** > **CI/CD**.
1. Expand **General pipelines**.
To open either project or group settings:
1. In the top bar, select **Search or go to** and find your project or group.
1. Select **Settings** > **CI/CD**.
1. Expand **General pipelines**.
To create a project:
1. In the upper-right corner, select **Create new** ({{< icon name="plus" >}}) and **New project/repository**.
To create a group:
1. In the upper-right corner, select **Create new** ({{< icon name="plus" >}}) and **New group**.
To open the Admin area:
1. In the upper-right corner, select **Admin**.
1. Select **Settings** > **CI/CD**.
You do not have to repeat In the left sidebar in your second step.
To open the Your work menu item:
1. In the top bar, select **Search or go to**.
1. Select **Your work**.
To select your avatar:
1. In the upper-right corner, select your avatar.
To save the selection in some dropdown lists:
1. Go to your issue.
1. In the right sidebar, in the **Iteration** section, select **Edit**.
1. From the dropdown list, select the iteration to associate this issue with.
1. Select any area outside the dropdown list.
To view all your projects:
1. In the top bar, select **Search or go to**.
1. Select **View all my projects**.
To view all your groups:
1. In the top bar, select **Search or go to**.
1. Select **View all my groups**.
If a step is optional, start the step with the word Optional followed by a period.
For example:
1. Optional. Enter a description for the job.
If a step is recommended, start the step with the word Recommended followed by a period.
For example:
1. Recommended. Enter a description for the job.
Write UI instructions instead of keyboard commands when both options exist. This guideline applies to GitLab and third-party applications, like VS Code.
Keyboard commands for GitLab are documented in GitLab keyboard shortcuts.
If the UI text sufficiently explains the fields in a section, do not include a task step for every field. Instead, summarize multiple fields in a single task step.
Use the phrase Complete the fields.
For example:
If you are documenting multiple fields and only one field needs explanation, do it in the same step:
To describe multiple fields, use unordered list items:
GitLab documentation uses two illustration types:
Illustrations can help the reader understand a concept, where they are in a complicated process, or how they should interact with the application. Use illustrations sparingly because:
If you must use illustrations in documentation, they should:
The following diagram illustrates the product analytics flow:.Use screenshots to show a portion of the GitLab user interface, if some relevant information can't be conveyed in text.
When you take screenshots:
lorem ipsum text.
Try to replicate how the feature would be used in a real-world scenario, and
use realistic text.To emphasize an area in a screenshot, use an arrow.
#EE2604. If you use the Preview application on macOS, this is the default red.image_name_vX_Y.png. For example, for a screenshot taken
from the pipelines page of GitLab 11.1, a valid name is pipelines_v11_1.png.devops_diagram_v11_1.png.img/ in the same directory where
the .md document that you're working on is located.
img directory within the docs directory.See also how to link and embed videos to illustrate the documentation.
Compress new images you add to the documentation. This helps reduce file sizes and improve page loading performance.
You can use pngquant, which is cross-platform and
open source. Install it by visiting the official website and following the
instructions for your OS.
You can compress images automatically or manually:
pngquant script.To use the pngquant script, in the root directory of your local copy of https://gitlab.com/gitlab-org/gitlab,
run the following commands as needed:
To check that all documentation PNG images are compressed:
bin/pngquant lint
To compress all documentation PNG images:
bin/pngquant compress
To compress specific files:
bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png
To compress all PNG files in a specific directory:
bin/pngquant compress doc/user/img
If the compression script creates .compressed files instead of compressing in place,
the files likely have PNG extensions but are other image formats (like JPEG).
The png_quantizator gem crashes on non-PNG files, preventing the script from completing.
Prerequisites:
Install GraphicsMagick:
# macOS:
brew install graphicsmagick
To convert image files to PNG format:
Check the file format:
file doc/user/img/problematic_file.png
The file command examines the file contents (magic bytes/headers) rather than
the extension. A misnamed JPEG file shows:
doc/user/img/problematic_file.png: JPEG image data, JFIF standard 1.01...
Convert the file to PNG format using GraphicsMagick:
gm convert problematic_file.png corrected_file.png
Run the compression script again.
If the original was a JPEG file, the converted PNG file might appear larger because PNG uses lossless compression while JPEG uses lossy compression.
Do not delete image files when you remove references to them from English documentation. Localized documentation (for example, Japanese pages) uses the same image files as the English docs. Even if an image is no longer referenced in English docs, it might still be in use by translated pages.
The docs site build process checks image paths. If you delete an image that's still in use,
the hugo_build job in your merge request pipeline will fail.
The images not used anywhere are cleaned up as part of the monthly maintenance.
Avoid animated images (such as animated GIFs). They can be distracting and annoying for users.
If you're describing a complicated interaction in the user interface and want to include a visual representation to help readers understand it, you can:
The Markdown code for including an image in a document is:
Alt text provides an accessible experience. Screen readers use alt text to describe the image, and alt text displays if an image fails to download.
Alt text should describe the context of the image, not the content. Add context that relates to the topic of the page or section. Consider what you would say about the image if you were helping someone read and interact with the page and they couldn't see it.
Do:
Do not:
When writing alt text:
**text** as star star text star star.alt="") instead of omitting the tag altogether when the image does not add any unique information to the page. For example, when the image is decorative or is already fully described in the body text or caption. An empty alt tag tells assistive technologies that you have omitted the text intentionally, while a missing alt tag is ambiguous.You can use an automatic screenshot generator to take and compress screenshots.
gdk/gitlab.bin/rake db:migrate RAILS_ENV=development.pngquant, see the tool website for more information: pngquantscripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>.gitlab/doc location defined by the it parameter in your script.To add an additional screenshot generator:
In the spec/docs_screenshots directory, add a new file with a _docs.rb extension.
Add the following information to your file:
require 'spec_helper'
RSpec.describe '<What I am taking screenshots of>', :js do
include DocsScreenshotHelpers # Helper that enables the screenshots taking mechanism
before do
page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page
end
To each it block, add the path where the screenshot is saved:
it '<path/to/images/directory>'
You can take a screenshot of a page with visit <path>.
To avoid blank screenshots, use expect to wait for the content to load.
You can take a screenshot of a single element.
Add the following to your screenshot generator file:
screenshot_area = find('<element>') # Find the element
scroll_to screenshot_area # Scroll to the element
expect(screenshot_area).to have_content '<content>' # Wait for the content you want to capture
set_crop_data(screenshot_area, <padding>) # Capture the element with added padding
Use spec/docs_screenshots/container_registry_docs.rb as a guide to create your own scripts.
Use a diagram to illustrate a process or the relationship between entities, if the information is too complex to be understood from text only.
To create a diagram, use either:
Mermaid is the recommended diagramming tool, but it is not suitable for all situations. For example, complex diagram requirements might result in a layout that is difficult to understand.
GUI diagramming tools can help authors overcome Mermaid's complexity and layout issue. Draw.io is the preferred GUI tool because, when you use the editor, both the diagram and its definition are stored in the SVG file, so it can be edited. Draw.io is also integrated with the GitLab wiki.
| Feature | Mermaid | Draw.io |
|---|---|---|
| Editor required | Text editor | Draw.io editor |
| WYSIWYG editing | {{< icon name="dash-circle" >}} No | {{< icon name="check-circle-filled" >}} Yes |
Text content findable by grep | {{< icon name="check-circle-filled" >}} Yes | {{< icon name="dash-circle" >}} No |
| Appearance controlled by | Web site's CSS | Diagram's author |
| File format | SVG | SVG |
| VS Code integration (with extensions) | {{< icon name="check-circle-filled" >}} Yes (Preview and local editing) | {{< icon name="check-circle-filled" >}} Yes (Preview and local editing) |
| Generated dynamically | {{< icon name="check-circle-filled" >}} Yes | {{< icon name="dash-circle" >}} No |
To create accessible and maintainable diagrams, follow these guidelines:
Keep diagrams simple and focused. Include only essential elements and information.
Use only shapes to distinguish between elements. Do not use color to differentiate elements, as diagrams must be compatible with both light and dark modes.
Recommended shapes are:
Shapes that represent the same element should have the same shape and size.
Add clear labels and brief descriptions to diagram elements.
For elements that have text, ensure adequate white space exists between the text and the shape's outline. If required, increase the size of the shape and all similar shapes in the diagram.
Include a title and brief description for the diagram.
Use GitLab Sans font for text, or Google Inter font as a fallback option.
For complex processes, consider creating multiple simple diagrams instead of one large diagram.
Validate diagrams work well when viewed on different devices and screen sizes.
Do not include links. Links embedded in diagrams with click actions are not testable with our link checking tools.
Update diagrams along with documentation or code when processes change to maintain accuracy.
To learn how to create diagrams with the Mermaid syntax, see the Mermaid user guide and the examples on the Mermaid site.
To create a diagram for GitLab documentation with Mermaid:
In the Mermaid Live Editor, create the diagram.
Copy the content of the Code pane and paste it in the Markdown file, wrapped in a mermaid code block. For more
details, see GitLab Flavored Markdown for Mermaid.
On the next line after declaring the type of diagram
(like flowchart or sequenceDiagram), add the following lines for accessibility:
accTitle: your diagram title here
accDescr: describe what your diagram does in a single sentence, with no line breaks.
Make sure the title and description follow the alternative text guidelines.
For example, this flowchart contains accessibility information:
```mermaid
flowchart TD
accTitle: Example diagram title
accDescr: A description of your diagram
A[Start here] -->|action| B[next step]
```
Use either the Draw.io web application or the (unofficial) VS Code Draw.io Integration extension to create the diagram. Each tool provides the same diagram editing experience, but the web application provides editable example diagrams.
Diagrams created by using Draw.io must comply with the general diagram guidelines and the Draw.io-specific guidelines.
When you create a diagram in Draw.io, it should be visually consistent with a diagram you would create with Mermaid. The following rules are an addition to the general diagram guidelines.
Fonts:
Inter.Shapes:
To create a diagram by using the Draw.io web application:
drawio.svg to indicate it can be edited in Draw.io.To create a diagram by using the Draw.io Integration extension for VS Code:
In the directory that will contain the diagram, create an empty file with the suffix
drawio.svg.
Open the file in VS Code then create the diagram.
Save the file.
The diagram's definition is stored in Draw.io-compatible format in the SVG file.
Add the SVG to the docs as an image. These SVGs use the same Markdown as other non-SVG images.
Don't use the Markdown emoji format, for example :smile:, for any purpose. Use
GitLab SVG icons instead.
You can use icons from the GitLab SVG library
directly in the documentation. For example, {{</* icon name="tanuki" */>}} renders as: {{< icon name="tanuki" >}}.
In most cases, avoid icons in text. However, use the icon when hover text is the only available way to describe a UI element. For example, Delete or Edit buttons often have hover text only.
When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses.
Select {{</* icon name="pencil" */>}} **Edit**. This generates as: Select {{< icon name="pencil" >}} Edit.Select **Edit** ({{</* icon name="pencil" */>}}). This generates as: Select Edit ({{< icon name="pencil" >}}).Do not use words to describe the icon:
Select **Erase job log** (the trash icon).Select **Erase job log** ({{</* icon name="remove" */>}}). This generates as: Select Erase job log ({{< icon name="remove" >}}).When the button doesn't have any hover text, describe the icon. Follow up by creating a UX bug issue to add hover text to the button to improve accessibility.
Select {{</* icon name="ellipsis_v" */>}}.Select the vertical ellipsis ({{</* icon name="ellipsis_v" */>}}). This generates as: Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).Adding GitLab YouTube video tutorials to the documentation is highly encouraged, unless the video is outdated. Videos should not replace documentation, but complement or illustrate it. If content in a video is fundamental to a feature and its key use cases, but isn't adequately covered in the documentation, you should:
Do not upload videos to the product repositories. Add a link or embed them instead.
To link to a video, include a YouTube icon so that readers can scan the page for videos before reading. For the link text, follow the general guidelines. Include the video's publication date after the link, to help identify videos that might be out-of-date.
<i class="fa-youtube-play" aria-hidden="true"></i>
For an overview, see [merge requests](https://link-to-video).
<!-- Video published on YYYY-MM-DD -->
You can link any up-to-date video that's useful to the GitLab user.
The GitLab documentation site supports embedded videos.
You can embed videos from the official YouTube account for GitLab only. For videos from other sources, link them instead.
In most cases, link to a video, because embedded videos take up a lot of space on the page and can be distracting to readers.
To embed a video:
https://www.youtube.com/watch?v=VIDEO-ID) and replace
the video title and link in the line under <div class="video-fallback">.<iframe> source (src) URL only
(https://www.youtube-nocookie.com/embed/VIDEO-ID),
and paste it, replacing the content of the src field in the
iframe tag.leave a blank line here
<div class="video-fallback">
See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
</div>
<figure class="video-container">
<iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe>
</figure>
<!-- Video published on YYYY-MM-DD -->
leave a blank line here
This is how it renders on the GitLab documentation site:
<div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe> </figure>With this formatting:
figure tag is required for semantic SEO and the video-container
class is necessary to make sure the video is responsive and displays on
different mobile devices.<div class="video-fallback"> is a fallback necessary for
/help, because the GitLab Markdown processor doesn't support iframes. It's
hidden on the documentation site, but is displayed by /help.www.youtube-nocookie.com domain enables the Privacy Enhanced Mode
of the YouTube embedded player. This mode allows users with restricted cookie preferences to view embedded videos.Linking to click-through demos should follow similar guidelines to videos.
For a click-through demo, see [Demo Title](https://link-to-demo).
<!-- Demo published on YYYY-MM-DD -->
Use alert boxes to call attention to information. Use them sparingly, and never have an alert box immediately follow another alert box.
Alert boxes are generated by using Markdown alerts:
> [!note]
> The text inside the alert box goes here.
The valid alert types are flag, note, warning, and disclaimer. The alert type is case-insensitive.
Use this alert type to describe a feature's availability. For information about how to format
flag alerts, see Document features deployed behind feature flags.
Use notes sparingly. Too many notes can make topics difficult to scan.
Instead of adding a note:
If you must use a note, use this format:
> [!note]
> This is something to note.
It renders on the GitLab documentation site as:
[!note] This is something to note.
Use a warning to indicate deprecated features, or to provide a warning about procedures that have the potential for data loss.
> [!warning]
> This is something to be warned about.
It renders on the GitLab documentation site as:
[!warning] This is something to be warned about.
If you must write about features we have not yet delivered, add a disclaimer about forward-looking statements near the content it applies to.
Disclaimer alerts are populated by using a template and should not include any other text.
Add a disclaimer like this:
> [!disclaimer]
It renders on the GitLab documentation site with the disclaimer text:
[!disclaimer]
If all of the content on the page is not available, use the disclaimer about forward-looking statements once at the top of the page.
If the content in a topic is not ready, use the disclaimer in the topic.
For more information, see Promising features in future versions.
Avoid using blockquotes in the product documentation. They can make text difficult to scan. Instead of a blockquote, consider using:
The GitLab Flavored Markdown (GLFM) page is a rare case that uses blockquotes to differentiate between plain text and rendered examples. However, in most cases, you should avoid them.
On the documentation site, you can format text to display as tabs.
[!warning] Do not put version history bullets, topic headings, HTML, or tabs in tabs. Only use paragraphs, lists, alert boxes, and code blocks. Other styles might not render properly. When in doubt, keep things simple.
To create a set of tabs, follow this example:
{{</* tabs */>}}
{{</* tab title="Tab one" */>}}
Here's some content in tab one.
{{</* /tab */>}}
{{</* tab title="Tab two" */>}}
Here's some other content in tab two.
{{</* /tab */>}}
{{</* /tabs */>}}
This code renders on the GitLab documentation site as:
{{< tabs >}}
{{< tab title="Tab one" >}}
Here's some content in tab one.
{{< /tab >}}
{{< tab title="Tab two" >}}
Here's some other content in tab two.
{{< /tab >}}
{{< /tabs >}}
For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter. For example:
Linux package (Omnibus), Helm chart (Kubernetes) (when documenting configuration edits, follow the
configuration edits guide)15.1 and earlier, 15.2 and laterUntil we implement automated testing for broken links to tabs, do not link directly to a single tab. For more information, see issue 225.
See Pajamas for more details on tabs.
Collapsible panels are closed by default and require a title. In the rendered documentation, you must expand the panel to view the content inside it.
{{</* collapsible title="Collapsible panel example" */>}}
This content appears inside the collapsible panel.
{{</* /collapsible */>}}
Only use collapsible panels on GitLab Duo pages in the availability details section for information about supported LLMs, editors, and self-hosted model availability.
Do not use collapsible panels for other content.
Use cards to create landing pages with links to sub-pages.
To create a set of cards, follow this example:
{{</* cards */>}}
- [The first page](first_page.md)
- [Another page](another/page.md)
- [One more page](one_more.md)
{{</* /cards */>}}
Additionally, cards support external URLs with optional descriptions. Use the following syntax:
{{</* cards */>}}
- [External page title](https://example.com "Optional Description")
{{</* /cards */>}}
Cards render only on the GitLab documentation site (https://docs.gitlab.com).
In the GitLab product help, a set of cards appears as an unordered list of links.
Card descriptions are populated from the description metadata on the Markdown page headers.
Use cards on top-level pages where the cards are the only content on the page.
Use the maintained versions shortcode to create an unordered list of the currently maintained GitLab versions as specified by the maintenance policy:
{{</* maintained-versions */>}}
Maintained versions render only on the pre-release version of the GitLab
documentation site (https://docs.gitlab.com). In all other cases and in
/help, a link to the documentation site is shown instead.
Use the shortcode for a glossary tooltip to provide a short definition that appears as a tooltip on hover. For example:
To do this thing, use {{</* glossary-tooltip text="the term" */>}}.
When the user hovers on {{< glossary-tooltip text="the term" >}}, a tooltip is displayed.
If a glossary page is configured for the tooltip and the user selects the anchor text, a related glossary page opens.
Use a glossary tooltip if the definition is a single, concise sentence, and try to use no more than 60 characters. For longer definitions, use a glossary page.
Do not use more than five to ten tooltips on a page. Each tooltip slows down the reader. Be careful not to overload users with definitions.
Use glossary tooltips in these cases:
artifact or analyzer.Do not use glossary tooltips in these cases:
Add glossary definitions to the
glossary.yaml file
in the docs-gitlab-com repository. Each definition should be short and not contain links.
Glossary terms are defined in the terms block with the following fields:
term_id
: Unique ID for the glossary term. To link to the glossary section, the term_id must match the
anchor on the glossary page for that term.
display_name
: Text that displays in the documentation. The display_name field is case insensitive. For
example, a text parameter in the shortcode of "attack surface" matches the term "Attack Surface"
in the glossary.yaml file.
glossary
: Optional. Link to the glossary definition for the term. If included, the term_id is
appended to the end of the glossary_url. For example,
/user/application_security/terminology#attack-surface.
short_description
: The text that appears when the user hovers over the tooltip.
Example glossary term definition in glossary.yaml file:
terms:
- term_id: attack-surface
display_name: Attack Surface
glossary: *security_glossary
short_description: The different places in an application that are vulnerable to attack
Glossaries are defined at the top of the glossary.yaml file.
The first line consists of two unique IDs:
glossary field must match this value.glossary_url
: Root URL of the glossary page that the term is defined in.
Example glossary definition in glossary.yaml file:
# Glossary files
security: &security_glossary
glossary_url: "/user/application_security/terminology"
Combining these examples results in the following:
short_description field is shown in a tooltip.attack-surface.Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically, it is better to rephrase relevant information in your own words or link to the source.
Do not promise to deliver features in a future release. For example, avoid phrases like, "Support for this feature is planned."
We cannot guarantee future feature work, and promises like these can raise legal issues. Instead, say that an issue exists. For example:
[issue <issue_number>](https://link-to-issue).[issue 12345](https://link-to-issue) proposes to change this behavior.You can say that we plan to remove a feature.
If you must document a future feature, use the disclaimer.
Refer to the information in this section when describing products and features in the GitLab product documentation.
If a feature or product name contains spaces, don't split the name with a line break. When names change, it is more complicated to search or grep text that has line breaks.
Product availability details provide information about a feature and are displayed under the topic title.
Read more about product availability details.
Certain styles should be applied to specific sections. Styles for specific sections are outlined in this section.
This section is displayed at the end of each document and can be omitted by adding a key into the front matter:
---
feedback: false
---
The default is to leave it there. If you want to omit it from a document, you must check with a technical writer before doing so.
When a restart or reconfigure of GitLab is required, avoid duplication by linking
to doc/administration/restart_gitlab.md
with text like this, replacing 'reconfigure' with 'restart' as needed:
Save the file and [reconfigure GitLab](../../../administration/restart_gitlab.md)
for the changes to take effect.
If the document resides outside of the doc/ directory, use the full path
instead of the relative link:
https://docs.gitlab.com/administration/restart_gitlab.
GitLab supports five official installation methods. If you're referring to words as part of sentences and titles, use the following phrases:
It's OK to add the explanatory parentheses when you use tabs:
Configuration procedures can require users to edit configuration files, reconfigure GitLab, or restart GitLab. In this case:
ruby, shell, or yaml).When describing a configuration edit, use this snippet, editing it as needed:
{{</* tabs */>}}
{{</* tab title="Linux package (Omnibus)" */>}}
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
external_url "https://gitlab.example.com"
```
1. Save the file and reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
{{</* /tab */>}}
{{</* tab title="Helm chart (Kubernetes)" */>}}
1. Export the Helm values:
```shell
helm get values gitlab > gitlab_values.yaml
```
1. Edit `gitlab_values.yaml`:
```yaml
global:
hosts:
gitlab:
name: gitlab.example.com
```
1. Save the file and apply the new values:
```shell
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
{{</* /tab */>}}
{{</* tab title="Docker" */>}}
1. Edit `docker-compose.yml`:
```yaml
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url "https://gitlab.example.com"
```
1. Save the file and restart GitLab:
```shell
docker compose up -d
```
{{</* /tab */>}}
{{</* tab title="Self-compiled (source)" */>}}
1. Edit `/home/git/gitlab/config/gitlab.yml`:
```yaml
production: &base
gitlab:
host: "gitlab.example.com"
```
1. Save the file and restart GitLab:
```shell
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
```
{{</* /tab */>}}
{{</* /tabs */>}}
It renders as:
{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Edit /etc/gitlab/gitlab.rb:
external_url "https://gitlab.example.com"
Save the file and reconfigure GitLab:
sudo gitlab-ctl reconfigure
{{< /tab >}}
{{< tab title="Helm chart (Kubernetes)" >}}
Export the Helm values:
helm get values gitlab > gitlab_values.yaml
Edit gitlab_values.yaml:
global:
hosts:
gitlab:
name: gitlab.example.com
Save the file and apply the new values:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
{{< /tab >}}
{{< tab title="Docker" >}}
Edit docker-compose.yml:
version: "3.6"
services:
gitlab:
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url "https://gitlab.example.com"
Save the file and restart GitLab:
docker compose up -d
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Edit /home/git/gitlab/config/gitlab.yml:
production: &base
gitlab:
host: "gitlab.example.com"
Save the file and restart GitLab:
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
{{< /tab >}}
{{< /tabs >}}