A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://docs.gitlab.com/development/documentation/styleguide/ below:

Documentation Style Guide | GitLab Docs

This document defines the standards for GitLab documentation, including grammar, formatting, and more. For guidelines on specific words, see the word list.

The GitLab voice

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.

Documentation is the single source of truth (SSoT)

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:

Topic types

GitLab uses topic types to organize the product documentation.

Topic types help users digest information more quickly. They also help address these issues:

Docs-first methodology

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.

Writing for localization

The GitLab documentation is not localized, but 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:

Markdown

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.

HTML in Markdown

Hard-coded HTML is valid, although it’s discouraged for a few reasons:

HTML is permitted if:

If you have an idea or request for a new element that would be useful on the Docs site, submit a feature request.

Heading levels in Markdown

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.

Description lists in Markdown

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

These lists render like this:

Term 1
Definition of Term 1
Term 2
Definition of Term 2
Shortcodes

Shortcodes are snippets of template code that we can include in our Markdown content to display non-standard elements on a page, such as alert boxes or tabs.

GitLab documentation uses the following shortcodes:

Language

GitLab documentation should be clear and easy to understand.

Active voice

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.

Customer perspective

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.

Building trust

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:

Self-referential writing

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.

Capitalization

As a company, we tend toward lowercase.

Topic titles

Use sentence case for topic titles. For example:

UI text

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

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

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.

Other terms

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.

Fake user information

Do not include real usernames or email addresses in the documentation.

For text:

For screenshots:

Fake URLs

When including sample URLs in the documentation, use:

Fake tokens

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

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:

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

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.

Prepositions

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:

Acronyms

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.

Numbers

For numbers in text, spell out zero through nine and use numbers for 10 and greater. For more information, see the Microsoft Style Guide.

Text Line length

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 -->
Punctuation

Follow these guidelines for punctuation.

When spacing content:

Do not use these punctuation characters:

Placeholder text

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>`**.
Quotation marks

Follow the Microsoft guidance for quotation marks.

Try to avoid quotation marks for user input and instead, use backticks.

Text formatting

When formatting text, use:

Bold

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:

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:

Inline code

Inline code is text that’s wrapped in single backticks (`). For example:

In the **Name** text box, enter `test`.

Use inline code for:

For example:

Code blocks

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:

To represent missing information in a code block, use a comment or an ellipsis. For example:

Keyboard commands

Use the HTML <kbd> tag when referring to keystroke presses. For example:

To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>.

This example renders as:

To stop the command, press Control+C.

Italics and emphasis

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.

Lists

Use lists to present information in a format that is easier to scan.

Choose between an ordered or unordered list

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
List markup Nesting inside a list item

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

  ![An image nested under list item 4.](image.png)

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

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.

Creation guidelines

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:

Editor extensions for table formatting

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:

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.

Updates to existing tables

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.

Feature tables

When creating tables of lists of features (such the features available to each role on the Permissions page), use these phrases:

Option Markdown Displayed result No {{< icon name="dash-circle" >}} No dash-circle No Yes {{< icon name="check-circle-filled" >}} Yes check-circle-filled Yes

Do not use these SVG icons in API documentation. Instead, 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. 1 App B Description text. 2

Footnotes:

  1. This is the first footnote.
  2. This is the second footnote.

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

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.

Inline links

Use inline links instead of reference links. Inline links are easier to parse and edit. (Vale rule: ReferenceLinks.yml)

Links in the same repository

To link to another documentation (.md) file in the same repository:

In the GitLab repository, do not link to the /development directory 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:

Links in separate repositories

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/).

Anchor links

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:

Changing links and titles

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.

Text for links

Follow these guidelines for link text.

Standard text

Use text that follows one of these patterns:

For example:

To expand on this text, use phrases like For more information about this feature, see...

Do not use the following constructions:

Descriptive text rather than here

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

Don’t:

Links to issues

When linking to an issue, include the issue number in the link. For example:

Do not use the pound sign (issue #12345).

Links to external documentation

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.

Links to handbook

Limit links to the handbook. Some links are unavoidable, like licensing terms, data usage and access policies, testing agreements, and terms and conditions.

Confidential or restricted access links

Don’t link directly to:

These links fail for:

If you must use one of these links:

Examples:

Link to specific lines of code

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.

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.

Navigation

When documenting how to navigate the GitLab UI:

Use these terms when referring to the main GitLab user interface elements:

Names for UI elements

All UI elements should be bold. The > in the navigation path should not be bold.

Guidance for individual UI elements is in the word list.

How to write navigation task steps

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. On the left sidebar, select **Search or go to** and find your project.
1. Select **Settings** > **CI/CD**.
1. Expand **General pipelines**.

To open group settings:

1. On the left sidebar, 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. On the left sidebar, 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. On the left sidebar, 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. On the left sidebar, at the top, select **Create new** (
 
           plus 
) and **New project/repository**.

To create a group:

1. On the left sidebar, at the top, select **Create new** (
 
           plus 
) and **New group**.

To open the Admin area:

1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings** > **CI/CD**.

You do not have to repeat On the left sidebar in your second step.

To open the Your work menu item:

1. On the left sidebar, select **Search or go to**.
1. Select **Your work**.

To select your avatar:

1. On the left sidebar, select your avatar.

To save the selection in some dropdown lists:

1. Go to your issue.
1. On 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. On the left sidebar, select **Search or go to**.
1. Select **View all my projects**.

To view all your groups:

1. On the left sidebar, select **Search or go to**.
1. Select **View all my groups**.
Optional steps

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.
Recommended steps

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.
Documenting keyboard shortcuts and commands

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.

Documenting multiple fields at once

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:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Repository.
  3. Expand Push rules.
  4. Complete the fields.

If you are documenting multiple fields and only one field needs explanation, do it in the same step:

  1. Expand Push rules.
  2. Complete the fields. Branch name must be a regular expression.

To describe multiple fields, use unordered list items:

  1. Expand General pipelines.
  2. Complete the fields.
Illustrations

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:

Screenshots

Use screenshots to show a portion of the GitLab user interface, if some relevant information can’t be conveyed in text.

Capture the screenshot

When you take screenshots:

Add callouts

To emphasize an area in a screenshot, use an arrow.

Image requirements

See also how to link and embed videos to illustrate the documentation.

Compress images

You should always compress any new images you add to the documentation. One known tool is pngquant, which is cross-platform and open source. Install it by visiting the official website and following the instructions for your OS.

If you use macOS and want all screenshots to be compressed automatically, read One simple trick to make your screenshots 80% smaller.

GitLab has a Ruby script to simplify the manual process. In the root directory of your local copy of https://gitlab.com/gitlab-org/gitlab, run in a terminal:

Animated images

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:

Add the image link to content

The Markdown code for including an image in a document is: ![Image description, used for alt tag](img/document_image_title_vX_Y.png)

Alternative text

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:

![A runner sending a request to the Docker API.](img/document_image_title_vX_Y.png)

Do not:

![Runner and Docker architecture](img/document_image_title_vX_Y.png)

When writing alt text:

Automatic screenshot generator

You can use an automatic screenshot generator to take and compress screenshots.

  1. Set up the GitLab Development Kit (GDK).
  2. Go to the subdirectory with your cloned GitLab repository, typically gdk/gitlab.
  3. Make sure that your GDK database is fully migrated: bin/rake db:migrate RAILS_ENV=development.
  4. Install pngquant, see the tool website for more information: pngquant
  5. Run scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>.
  6. Identify the location of the screenshots, based on the gitlab/doc location defined by the it parameter in your script.
  7. Commit the newly created screenshots.
Extending the tool

To add an additional screenshot generator:

  1. In the spec/docs_screenshots directory, add a new file with a _docs.rb extension.

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

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

Single-element screenshots

You can take a screenshot of a single element.

Use spec/docs_screenshots/container_registry_docs.rb as a guide to create your own scripts.

Diagrams

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 (recommended) or Draw.io.

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 dash-circle No check-circle-filled Yes Text content findable by grep check-circle-filled Yes dash-circle No Appearance controlled by Web site’s CSS Diagram’s author File format SVG SVG VS Code integration (with extensions) check-circle-filled Yes (Preview and local editing) check-circle-filled Yes (Preview and local editing) Generated dynamically check-circle-filled Yes dash-circle No Guidelines

To create accessible and maintainable diagrams, follow these guidelines:

Create a diagram with Mermaid

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:

  1. In the Mermaid Live Editor, create the diagram.

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

  3. To add GitLab font styling to your diagram, between the Mermaid code block declaration and the type of diagram, add the following line:

    %%{init: { "fontFamily": "GitLab Sans" }}%%

  4. 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 both accessibility and font information:

```mermaid
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
    accTitle: Example diagram title
    accDescr: A description of your diagram

    A[Start here] -->|action| B[next step]
```
Create a diagram with Draw.io

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.

Use the web application

To create a diagram by using the Draw.io web application:

  1. In the Draw.io web application, create the diagram. Follow the style guidelines.
  2. Save the diagram:
    1. In the Draw.io web application, select File > Export as > SVG.
    2. Select the Include a copy of my diagram: All pages checkbox, then select Export. Use the file extension drawio.svg to indicate it can be edited in Draw.io.
  3. Add the SVG to the docs as an image. These SVGs use the same Markdown as other non-SVG images.
Use the VS Code extension

To create a diagram by using the Draw.io Integration extension for VS Code:

  1. In the directory that will contain the diagram, create an empty file with the suffix drawio.svg.

  2. Open the file in VS Code then create the diagram. Follow the style guidelines.

  3. Save the file.

    The diagram’s definition is stored in Draw.io-compatible format in the SVG file.

  4. Add the SVG to the docs as an image. These SVGs use the same Markdown as other non-SVG images.

Style 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 style guidelines.

Fonts:

Shapes:

Colors:

Emoji

Don’t use the Markdown emoji format, for example :smile:, for any purpose. Use GitLab SVG icons instead.

GitLab SVG icons

You can use icons from the GitLab SVG library directly in the documentation. For example, {{< icon name="tanuki" >}} renders as: 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.

Do not use words to describe the icon:

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.

Videos

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.

Link to video

To link to a video, include a YouTube icon so that readers can scan the page for videos before reading. 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 [Video Title](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.

Embed videos

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:

  1. Copy the code from this procedure and paste it into your Markdown file. Leave a blank line above and below it. Do not edit the code (don’t remove or add any spaces).
  2. In YouTube, visit the video URL you want to display. Copy the regular URL from your browser (https://www.youtube.com/watch?v=VIDEO-ID) and replace the video title and link in the line under <div class="video-fallback">.
  3. In YouTube, select Share, and then select Embed.
  4. Copy the <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.
  5. Include the video’s publication date below the link, to help identify videos that might be out-of-date.
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:

With this formatting:

Link to click-through demos

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 -->
Alert boxes

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 a Hugo shortcode:

{{< alert type="note" >}}

This is something to note.

{{< /alert >}}

The valid alert types are flag, note, warning, and disclaimer.

Alert boxes render only on the GitLab documentation site (https://docs.gitlab.com). In the GitLab product help, alert boxes appear as plain text.

Flag

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.

Note

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:

{{< alert type="note" >}}

This is something to note.

{{< /alert >}}

It renders on the GitLab documentation site as:

This is something to note.

Warning

Use a warning to indicate deprecated features, or to provide a warning about procedures that have the potential for data loss.

{{< alert type="warning" >}}

This is something to be warned about.

{{< /alert >}}

It renders on the GitLab documentation site as:

This is something to be warned about.

Disclaimer

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:

{{< alert type="disclaimer" />}}

It renders on the GitLab documentation site as:

This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.

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.

Blockquotes

For highlighting a text inside a blockquote, use this format:

It renders on the GitLab documentation site as:

This is a blockquote.

If the text spans multiple lines, split them.

For multiple paragraphs, use the symbol > before every line:

> This is the first paragraph.
>
> This is the second paragraph.
>
> - This is a list item
> - Second item in the list

It renders on the GitLab documentation site as:

This is the first paragraph.

This is the second paragraph.

Tabs

On the documentation site, you can format text to display as tabs.

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:

Here’s some content in tab one.

Here’s some other content in tab two.

For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter. For example:

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

Cards

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 >}}

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.

Maintained versions

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.

Plagiarism

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 out to the other source.

Promising features in future versions

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:

You can say that we plan to remove a feature.

If you must document a future feature, use the disclaimer.

Products and features

Refer to the information in this section when describing products and features in the GitLab product documentation.

Avoid line breaks in names

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

Product availability details provide information about a feature and are displayed under the topic title.

Read more about product availability details.

Specific sections

Certain styles should be applied to specific sections. Styles for specific sections are outlined in this section.

Help and feedback section

This section is displayed at the end of each document and can be omitted by adding a key into the front matter:

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.

GitLab restart

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.

How to document different installation methods

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:

Use tabs to describe a GitLab Self-Managed configuration procedure

Configuration procedures can require users to edit configuration files, reconfigure GitLab, or restart GitLab. In this case:

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:

  1. Edit /etc/gitlab/gitlab.rb:

    external_url "https://gitlab.example.com"

  2. Save the file and reconfigure GitLab:

    sudo gitlab-ctl reconfigure

  1. Export the Helm values:

    helm get values gitlab > gitlab_values.yaml

  2. Edit gitlab_values.yaml:

    global:
  hosts:
    gitlab:
      name: gitlab.example.com

  3. Save the file and apply the new values:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. Edit docker-compose.yml:

    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url "https://gitlab.example.com"

  2. Save the file and restart GitLab:

  1. Edit /home/git/gitlab/config/gitlab.yml:

    production: &base
  gitlab:
    host: "gitlab.example.com"

  2. Save the file and restart GitLab:

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

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