2020-07-29 12:09:45 +00:00
---
stage: Create
group: Source Code
2021-10-15 15:10:09 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-07-29 12:09:45 +00:00
---
2021-02-09 18:09:59 +00:00
# AsciiDoc **(FREE)**
2019-06-14 07:53:08 +00:00
GitLab uses the [Asciidoctor ](https://asciidoctor.org ) gem to convert AsciiDoc content to HTML5.
2019-07-08 23:14:29 +00:00
Consult the [Asciidoctor User Manual ](https://asciidoctor.org/docs/user-manual/ ) for a complete Asciidoctor reference.
2019-06-14 07:53:08 +00:00
## Syntax
Here's a brief reference of the most commonly used AsciiDoc syntax.
2019-10-08 03:05:52 +00:00
You can find the full documentation for the AsciiDoc syntax at < https: / / asciidoctor . org / docs / > .
2019-06-14 07:53:08 +00:00
### Paragraphs
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
A normal paragraph.
Line breaks are not preserved.
```
Line comments, which are lines that start with `//` , are skipped:
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// this is a comment
```
A blank line separates paragraphs.
2021-03-05 18:09:17 +00:00
A paragraph with the `[%hardbreaks]` option preserves line breaks:
2019-06-14 07:53:08 +00:00
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
[%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
2021-01-23 00:08:46 +00:00
fixed-width font:
2019-06-14 07:53:08 +00:00
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
This literal paragraph is indented with one space.
As a consequence, *text formatting* , spaces,
and lines breaks will be preserved.
```
2020-12-16 03:09:46 +00:00
Admonition paragraphs grab the reader's attention:
2019-06-14 07:53:08 +00:00
2020-12-16 03:09:46 +00:00
- `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.`
2019-06-14 07:53:08 +00:00
### Text Formatting
**Constrained (applied at word boundaries)**
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
*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)**
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
**C**reate+**R**ead+**U**pdate+**D**elete
fan__freakin__tastic
``mono``culture
```
**Replacements**
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
A long time ago in a galaxy far, far away...
(C) 1976 Arty Artisan
I believe I shall--no, actually I won't.
```
**Macros**
2020-07-14 15:09:05 +00:00
```plaintext
2021-10-15 15:10:09 +00:00
// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
2019-06-14 07:53:08 +00:00
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
2020-04-06 21:09:19 +00:00
**User-defined attributes**
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// define attributes in the document header
:name: value
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
: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}.
```
2020-04-06 21:09:19 +00:00
**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). |
2019-06-14 07:53:08 +00:00
### Links
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
https://example.org/page[A webpage]
link:../path/to/file.txt[A local file]
xref:document.adoc[A sibling document]
mailto:hello@example.org[Email to say hello!]
```
### Anchors
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
[[idname,reference text]]
// or written using normal block attributes as `[#idname,reftext=reference text]`
A paragraph (or any block) with an anchor (aka ID) and reftext.
See < < idname > > or < < idname , optional text of internal link > >.
xref:document.adoc#idname[Jumps to anchor in another document].
This paragraph has a footnote.footnote:[This is the text of the footnote.]
```
### Lists
#### Unordered
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
* level 1
** level 2
*** level 3
**** level 4
2021-10-15 15:10:09 +00:00
***** level 5
2019-06-14 07:53:08 +00:00
* back at level 1
+
Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block).
.Some Authors
[circle]
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson
```
#### Ordered
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
.Remember your Roman numerals?
[upperroman]
. is one
. is two
. is three
```
#### Checklist
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
* [x] checked
* [ ] not checked
```
2019-07-12 08:09:23 +00:00
2021-01-27 00:08:53 +00:00
<!-- vale gitlab.Spelling = NO -->
2019-06-14 07:53:08 +00:00
#### Callout
2021-01-27 00:08:53 +00:00
<!-- vale gitlab.Spelling = YES -->
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// enable callout bubbles by adding `:icons: font` to the document header
[,ruby]
----
puts 'Hello, World!' # < 1 >
----
< 1 > Prints `Hello, World!` to the console.
```
#### Description
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
first term:: description of first term
second term::
description of second term
```
2019-07-12 08:09:23 +00:00
2019-06-14 07:53:08 +00:00
### Document Structure
#### Header
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
= Document Title
Author Name < author @ example . org >
v1.0, 2019-01-01
```
2019-07-12 08:09:23 +00:00
2019-06-14 07:53:08 +00:00
#### Sections
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
= Document Title (Level 0)
== Level 1
=== Level 2
==== Level 3
===== Level 4
====== Level 5
== Back at Level 1
```
#### Includes
2022-02-10 15:12:42 +00:00
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 file name from `.adoc` to `.asciidoc` .
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
include::basics.adoc[]
// define -a allow-uri-read to allow content to be read from URI
include::https://example.org/installation.adoc[]
```
2019-07-12 08:09:23 +00:00
2021-10-15 15:10:09 +00:00
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. You can include up to 32 documents, which is
inclusive of transitive dependencies.
2020-01-30 21:08:47 +00:00
2019-06-14 07:53:08 +00:00
### Blocks
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
--
open - a general-purpose content wrapper; useful for enclosing content to attach to a list item
--
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING
// enable admonition icons by setting `:icons: font` in the document header
[NOTE]
====
admonition - a notice for the reader, ranging in severity from a tip to an alert
====
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
====
example - a demonstration of the concept being documented
====
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
.Toggle Me
[%collapsible]
====
collapsible - these details are revealed by clicking the title
====
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
****
sidebar - auxiliary content that can be read independently of the main content
****
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
....
literal - an exhibit that features program output
....
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
----
listing - an exhibit that features program input, source code, or the contents of a file
----
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
[,language]
----
source - a listing that is embellished with (colorized) syntax highlighting
----
```
2020-07-14 15:09:05 +00:00
````plaintext
2019-06-14 07:53:08 +00:00
\```language
fenced code - a shorthand syntax for the source block
\```
2020-03-12 09:09:55 +00:00
````
2019-06-14 07:53:08 +00:00
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
[,attribution,citetitle]
____
quote - a quotation or excerpt; attribution with title of source are optional
____
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
[verse,attribution,citetitle]
____
verse - a literary excerpt, often a poem; attribution with title of source are optional
____
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
++++
pass - content passed directly to the output document; often raw HTML
++++
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// activate stem support by adding `:stem:` to the document header
[stem]
++++
x = y^2
++++
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
////
comment - content which is not included in the output document
////
```
### Tables
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
.Table Attributes
[cols=>1h;2d,width=50%,frame=topbot]
|===
| Attribute Name | Values
| options
| header,footer,autowidth
| cols
| colspec[;colspec;...]
| grid
| all \| cols \| rows \| none
| frame
| all \| sides \| topbot \| none
| stripes
| all \| even \| odd \| none
| width
| (0%..100%)
| format
| psv {vbar} csv {vbar} dsv
|===
```
2020-07-18 18:09:40 +00:00
### Colors
2021-03-17 15:09:03 +00:00
It's possible to have color written in `HEX` , `RGB` , or `HSL` format rendered with a color indicator.
2020-07-18 18:09:40 +00:00
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])` ``
2021-03-05 18:09:17 +00:00
Color written inside backticks is followed by a color "chip":
2020-07-18 18:09:40 +00:00
```plaintext
- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)`
```
### STEM
To activate equation and formula support,
set the `stem` attribute in the document's header to `latexmath` .
2021-03-05 18:09:17 +00:00
Equations and formulas are rendered using [KaTeX ](https://katex.org/ ):
2020-07-18 18:09:40 +00:00
```plaintext
:stem: latexmath
latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]
[stem]
++++
sqrt(4) = 2
++++
A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))].
```
### 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
2020-08-13 09:10:09 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31818) in GitLab 13.3.
2020-07-18 18:09:40 +00:00
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 within Mermaid diagrams.
2021-10-15 15:10:09 +00:00
To generate a diagram or flowchart, enter your text in a `mermaid` block:
2020-07-18 18:09:40 +00:00
```plaintext
[mermaid]
----
graph LR
A[Square Rect] -- Link text --> B((Circle))
A --> C(Round Rect)
B --> D{Rhombus}
C --> D
----
```
2020-11-28 21:09:37 +00:00
#### 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.
2021-10-15 15:10:09 +00:00
After Kroki is enabled, you can create diagrams in AsciiDoc and Markdown documents.
2020-11-28 21:09:37 +00:00
Here's an example using a GraphViz diagram:
**AsciiDoc**
```plaintext
[graphviz]
....
digraph G {
Hello->World
}
....
```
**Markdown**
````markdown
```graphviz
digraph G {
Hello->World
}
```
````
2020-07-18 18:09:40 +00:00
#### PlantUML
To make PlantUML available in GitLab, a GitLab administrator needs to enable it first.
Read more in [PlantUML & GitLab ](../administration/integration/plantuml.md ).
2021-10-15 15:10:09 +00:00
After PlantUML is enabled, enter your text in a `plantuml` block:
2020-07-18 18:09:40 +00:00
```plaintext
[plantuml]
----
Bob -> Alice : hello
----
```
2019-06-14 07:53:08 +00:00
### Multimedia
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
image::screenshot.png[block image,800,450]
Press image:reload.svg[reload,16,opts=interactive] to reload the page.
video::movie.mp4[width=640,start=60,end=140,options=autoplay]
2021-12-17 00:15:24 +00:00
```
2019-06-14 07:53:08 +00:00
2021-12-17 00:15:24 +00:00
GitLab does not support embedding YouTube and Vimeo videos in AsciiDoc content.
Use a standard AsciiDoc link:
2019-06-14 07:53:08 +00:00
2021-12-17 00:15:24 +00:00
```plaintext
https://www.youtube.com/watch?v=BlaZ65-b7y0[Link text for the video]
2019-06-14 07:53:08 +00:00
```
### Breaks
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// thematic break (aka horizontal rule)
---
```
2020-07-14 15:09:05 +00:00
```plaintext
2019-06-14 07:53:08 +00:00
// page break
< < <
```