Text and formatting

For the main style guide page, see Documentation Style Guide.

Text

  • Write in Markdown.

  • Insert an empty line for new paragraphs.

  • Insert an empty line between different markups (for example, after every paragraph, heading, and list). Example:

    markdown
    ## Heading

Paragraph.

- List item 1
- List item 2

Line length

To make the source content easy to read, and to compare diffs, follow these best practices.

  • Split long lines at approximately 100 characters, but do not split links.
  • Try to avoid splitting lines between logical word groupings, keep them together on the same line.
  • Start each new sentence on a new line.

For example:

  • Use:

    markdown
    This long line talks about how to manage a GitLab Self-Managed instance
deployed to Google Cloud for Education.

  • Instead of:

    markdown
    This long line talks about how to manage a GitLab
Self-Managed instance deployed to Google Cloud for
Education.

Comments

To embed comments in Markdown, use standard HTML comments that are not rendered when published. Example:

html
<!-- 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.

Punctuation

Follow these guidelines for punctuation.

For punctuation in the UI, see Pajamas.

  • End complete sentences with a period.
  • Use serial (Oxford) commas before the final and or or in a list of three or more items. (Tested in OxfordComma.yml.)

When spacing content:

  • Use one space between sentences. (Use of more than one space is tested in SentenceSpacing.yml.)
  • Do not use non-breaking spaces. Use standard spaces instead. (Tested in lint-doc.sh.)
  • Do not use tabs for indentation. Use spaces instead. Consider configuring your code editor to output spaces instead of tabs when pressing the Tab key.

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

Ellipses

Avoid using ellipses. If you must use them, for example, in a code block or CLI response, use three periods with no space (...).

Do not use the &hellip; HTML entity or the &#8230; HTML code because these cause issues with how code blocks render.

Do not include any ellipses when documenting UI text. For example, use:

  • Search or go to

Instead of:

  • Search or go to…

For more information, see the Microsoft Style Guide.

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:

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

  • Inline code style for inputs, outputs, code, and similar.
  • Code blocks for command line examples, and multi-line inputs, outputs, code, and similar.
  • <kbd> for keyboard commands.

Bold

Do not use bold for keywords or emphasis.

Before GitLab 19.5, we tried to only use bold for:

  • UI elements with a visible label.
  • Navigation paths.

Now, we use shortcodes for UI elements and navigation paths.

You might still see bold in documentation that has not been updated to use shortcodes yet, or for hardcoded strings. For example:

  • On the Issues page… (not updated yet)
  • Select Jenkins. (hardcoded)

Inline code

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

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

Use inline code for:

  • Text a user enters in the UI.
  • Short inputs and outputs like true, false, Job succeeded, and similar.
  • Filenames, configuration parameters, keywords, and code. For example, .gitlab-ci.yml, --version, or rules:.
  • Short error messages.
  • API and HTTP methods (POST).
  • HTTP status codes. Full (404 File Not Found) and abbreviated (404).
  • HTML elements. For example, <sup>. Include the angle brackets.

For example:

  • In the Name text box, enter test.
  • Use the rules: CI/CD keyword to control when to add jobs to a pipeline.
  • Send a DELETE request to delete the runner. Send a POST request to create one.
  • The job log displays Job succeeded when complete.

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
```markdown
This is a code block that uses Markdown to demonstrate **bold** and `backticks`.
```

When you use code blocks:

  • Add a blank line above and below code blocks.
  • Use one of the supported syntax names or opencypher. Use plaintext if no better option is available.
  • Use quadruple backticks (````) 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
  • // ...

Keyboard commands

When writing about keystroke presses:

  • Use the HTML <kbd> tag.
  • Do not use spaces between <kbd> tags in key combinations.
  • Spell out the full name of the key, except for Alt (Vale rule: SubstitutionWarning.yml).
  • Use uppercase for the first letter of the key if it’s an action key. For example, Shift, Command, Delete.
  • Use uppercase if the key is a letter.
  • Use ↑, ↓, ←, 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 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.

Emoji

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