AsciiDoc

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab uses the Asciidoctor gem to convert AsciiDoc content to HTML5. Consult the Asciidoctor User Manual for a complete Asciidoctor reference.

You can use AsciiDoc in the following areas:

Wiki pages
AsciiDoc documents (.adoc or .asciidoc) inside repositories

Syntax

Here's a brief reference of the most commonly used AsciiDoc syntax. You can find the full documentation for the AsciiDoc syntax at https://asciidoctor.org/docs/.

Paragraphs

A normal paragraph.
Line breaks are not preserved.

Line comments, which are lines that start with //, are skipped:

// this is a comment

A blank line separates paragraphs.

A paragraph with the [%hardbreaks] option preserves line breaks:

[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.

An indented (literal) paragraph disables text formatting, preserves spaces and line breaks, and is displayed in a fixed-width font:

 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.

Admonition paragraphs grab the reader's attention:

NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.
TIP: Lists can be indented. Leading whitespace is not significant.

Text Formatting

Constrained (applied at word boundaries)

*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)

Unconstrained (applied anywhere)

**C**reate+**R**ead+**U**pdate+**D**elete
fan__freakin__tastic
``mono``culture

Replacements

A long time ago in a galaxy far, far away...
(C) 1976 Arty Artisan
I believe I shall--no, actually I won't.

Macros

// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow].
The pass:c[->] operator is often referred to as the stabby lambda.
Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}].
// activate stem support by adding `:stem:` to the document header
stem:[sqrt(4) = 2]

Attributes

User-defined attributes

// define attributes in the document header
:name: value

:url-gem: https://rubygems.org/gems/asciidoctor

You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
C{pp} is not required, only Ruby.
Use a leading backslash to output a word enclosed in curly braces, like \{name}.

Environment attributes

GitLab sets the following environment attributes:

Attribute	Description
`docname`	Root name of the source document (no leading path or file extension).
`outfilesuffix`	File extension corresponding to the backend output (defaults to `.adoc` to make inter-document cross references work).

Links

// this is a comment
```0

### Anchors

```plaintext
// this is a comment
```1

### Lists

#### Unordered

```plaintext
// this is a comment
```2

#### Ordered

```plaintext
// this is a comment
```3

#### Checklist

```plaintext
// this is a comment
```4

#### Callout

```plaintext
// this is a comment
```5

#### Description

```plaintext
// this is a comment
```6

### Document Structure

#### Header

```plaintext
// this is a comment
```7

#### Sections

```plaintext
// this is a comment
```8

#### Includes

NOTE:
[Wiki pages](project/wiki/index.md#create-a-new-wiki-page) created with the AsciiDoc
format are saved with the file extension `.asciidoc`. When working with AsciiDoc wiki
pages, change the filename from `.adoc` to `.asciidoc`.

```plaintext
// this is a comment
```9

To guarantee good system performance and prevent malicious documents from causing
problems, GitLab enforces a maximum limit on the number of include directives
processed in any one document. By default, a document can have up to 32 include directives, which is
inclusive of transitive dependencies. To customize the number of processed includes directives, change
the application setting `asciidoc_max_includes` with the
[application settings API](../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls).

NOTE:
The current maximum allowed value for `asciidoc_max_includes` is 64. If the value is
too high, it might cause performance issues in some situations.

To use includes from separate pages or external URLs, enable the `allow-uri-read`
in [application settings](../administration/wikis/index.md#allow-uri-includes-for-asciidoc).

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```0

### Blocks

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```1

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```2

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```3

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```4

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```5

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```6

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```7

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```8

```plaintext
[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.
```9

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```0

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```1

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```2

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```3

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```4

### Tables

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```5

### Colors

It's possible to have color written in `HEX`, `RGB`, or `HSL` format rendered with a color indicator.
Supported formats (named colors are not supported):

- `HEX`: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
- `RGB`: `` `RGB[A](R, G, B[, A])` ``
- `HSL`: `` `HSL[A](H, S, L[, A])` ``

Color written inside backticks is followed by a color "chip":

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```6

### Equations and Formulas (STEM)

If you need to include Science, Technology, Engineering, and Math (STEM)
expressions, set the `stem` attribute in the document's header to `latexmath`.
Equations and formulas are rendered using [KaTeX](https://katex.org/):

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```7

### Diagrams and flowcharts

It's possible to generate diagrams and flowcharts from text in GitLab using
[Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com).

#### Mermaid

Visit the [official page](https://mermaidjs.github.io/) for more details.
If you're new to using Mermaid or need help identifying issues in your Mermaid code,
the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool
for creating and resolving issues in Mermaid diagrams.

To generate a diagram or flowchart, enter your text in a `mermaid` block:

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```8

#### Kroki

Kroki supports more than a dozen diagram libraries.
To make Kroki available in GitLab, a GitLab administrator needs to enable it first.
Read more in the [Kroki integration](../administration/integration/kroki.md) page.

After Kroki is enabled, you can create diagrams in AsciiDoc and Markdown documents.
Here's an example using a GraphViz diagram:

**AsciiDoc**

```plaintext
 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.
```9

**Markdown**

```plaintext
*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)
```0

#### PlantUML

PlantUML integration is enabled on GitLab.com. To make PlantUML available in self-managed
installation of GitLab, a GitLab administrator [must enable it](../administration/integration/plantuml.md).

After PlantUML is enabled, enter your text in a `plantuml` block:

```plaintext
*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)
```1

### Multimedia

```plaintext
*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)
```2

GitLab does not support embedding YouTube and Vimeo videos in AsciiDoc content.
Use a standard AsciiDoc link:

```plaintext
*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)
```3

### Breaks

```plaintext
*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)
```4

```plaintext
*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)
```5