Handbook Markdown Guide

Read through our Markdown Style Guide!

The guide covers usage of Markdown. If you’re looking for something and can’t find it, it may be on the shortcodes page.

Markdown Style Guide for the Handbook

This website was generated by Hugo, a blog-aware Static Site Generator (SSG) widely used by web developers. Markup language is part of the structure of any SSG. It is a system to write documents making them somehow syntactically distinguishable from text. Lightweight markup languages have a simplified and unobtrusive syntax, designed to be easily written within any text editor. That’s what we use to write our content. The majority of SSGs use markdown engines for this purpose. Read through our blog post on Modern Static Site Generators to understand how they work.

For The GitLab Handbook we use Goldmark, which is an advanced Markdown engine written in Go and comes bundled as part of Hugo. It implements the CommonMark markdown standard, it’s is extensible and very fast at transforming Markdown to HTML. As such, we encourage use of Markdown as much as possible, though we allow HTML inline (MD033).

If you never have written a single line in markdown markup, don’t worry, it’s easy to learn and even easier to use. You’ll probably be surprised how handy it is once you get used to it. And you’ll miss it whenever the tech you’re using doesn’t support markdown.

In most of GitLab text areas you’ll find markdown support. We have a number of markdown engines in GitLab so the markup will not behave equally “GitLabwide”. For GitLab.com, GitLab CE and GitLab EE text areas, the markdown engine is currently CommonMarker. Here you can find the markdown style guide for them. In the ther handbook projects you’ll see kramdown used.

This guide has been made to make it easier for everyone to use Hugo and Goldmark features and save a lot of time writing content for The GitLab Handbook .

There are different possible syntaxes for most of the markups described below, but this guide is to be considered the standard for The GitLab Handbook .

For information on how markdown is verified in the pipeline, refer to the development docs. Relevant customized markdownlint rules are noted in the format MD###.


Headings

Markdown
## Heading h2

### Heading h3

#### Heading h4

Output

Heading h2

Heading h3

Heading h4

Notes on heading structure:

  • We don’t use h1 headings, as they already are displayed on every page as its title, and we should not apply more than one h1 per page (MD002, MD041).

    When you use a top level heading, or an <h1>, you’re setting up a semantic relationship between that heading and the remainder of the content on a page, describing what it is about. If you then use a second <h1> on the same page, you’re creating some potential confusion, because someone, or a search engine might see that as the ending of the semantic relationship between the content after the first <h1> and the start of this new <h1>. SEO Guide

  • Always start with h2 (##), and respect the order h2 → h3 → h4. Never skip the hierarchy level, such as h2 → h4.

    The six heading elements, H1 through H6, denote section headings. Although the order and occurrence of headings is not constrained by the HTML DTD, documents should not skip levels (for example, from H1 to H3), as converting such documents to other representations is often problematic. W3C

  • To prevent confusion, headings at the same level should not be duplicated (MD024).

Notes on individual headings:

  • Always leave a blank space between the hash # and the text next to it, otherwise it won’t render properly.
  • For keeping the text clear and the markdown consistent, there should be an empty line before and after.
  • We enforce using the “atx” style of heading, where the heading starts with one or more hashes (MD003).
  • While emphasis instead of header is allowed (MD036), it is not recommended.
  • Headings should not end in punctuation (MD026).

Paragraphs, breaks, and horizontal lines

Regular paragraphs are obtained by just writing text lines. If you hit enter between two lines, both lines will be joined into a single paragraph, which is called wrapping text. But, if you leave a blank line between them, they will split into two paragraphs.

In some Git tools, diffs in future MRs may be easier to understand with additional line breaks, however GitLab’s web interface as well as many desktop Git tools feature substring change highlighting within lines and side-by-side or similar version comparison so there is no need for artificial line breaks.

Wrapping Text

Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text. Do not leave blank spaces after the last word of the line broken within a paragraph, unless you want it to be intentionally broken with a <br>.

Regular paragraphs and automatic join

Markdown
This text is a paragraph.
This won't be another paragraph, it will join the line above it.

This will be another paragraph, as it has a blank line above it.
Output

This text is a paragraph. This won't be another paragraph, it will join the line above it.

This will be another paragraph, as it has a blank line above it.

Additional breaks

In case you need an additional break (or some extra space between lines), you can simply use the HTML break tag <br>, leaving blank lines above and below it:

Markdown
Text A
<!-- blank line -->
<br>
<!-- blank line -->
Text B
Output

Text A


Text B

Horizontal lines

A sequence of three or more dashes will produce a horizontal line, but let’s use always 3 as standard (MD035). Leave blank lines after and before it:

Markdown
Text
<!-- blank line -->
---
<!-- blank line -->
Text
Output

Text


Text

Emphasis: bold and italic

To display bold or italic text, wrap it in 2 stars (for bold) or underscores (for italic). For both italic and bold, wrap it in 3 stars:

Markdown
This is **bold** and this is _italic_.

This is _**bold and italic**_.
Output

This is bold and this is italic.

This is bold and italic.

Markdown doesn’t natively support underlined text. If necessary you can hardcode it with the HTML tag ins (<ins>underlined text</ins>), however, it is inadvisable to do so.


There are a few different ways to display links with markdown markup, but to keep some standards, let’s try to use the following options only.

We’d rather use inline links, such as [Text to display](link), as they are easier to maintain. To make an inline link pen in a new tab, you can add {:target="_blank"} to the end. Ex: [Text to display](link){:target="_blank"}

Use relative links when referring to links found on handbook.gitlab.com.

When linking to other pages within the same handbook (or repository), use relative links. You can either link to the markdown file (which is the easiest when using the editor) or the final version of the link. Some examples:

Page you’re editing Page you’re linking to Link to the markdown file Link to the final version
/handbook/company/culture/_index.md /handbook/company/culture/working-remote.md ./working-remote.md ./working-remote/
/handbook/company/culture/_index.md /handbook/company/culture/all-remote/coffee-chats.md ./all-remote/coffee-chats.md ./all-remote/coffee-chats/
/handbook/company/culture/_index.md /handbook/company/okrs/cadence.md ../okrs/cadence.md ../okrs/cadence/
/handbook/company/culture/_index.md /handbook/engineering/infrastructure/_index.md ../../engineering/infrastructure/_index.md ../../engineering/infrastructure/

Alternatively, you can link to the final version of the page link without the domain if it’s in the same handbook. For example, a link to our blog handbook page should look like this /handbook/marketing/blog/ and not this https://handbook.gitlab.com/handbook/marketing/blog/.

Only use the absolute (not relative) link, including the domain https://example.com, if the page is not in the same repository. For example if you are editing the public handbook and need to link to an internal handbook page.

Hugo can reference reference pages without having to use the full relative path. However, for consistency and easy of use, we use plain Markdown links, and avoid using the Hugo ref or relref shortcodes.

For links to GitLab.com or anywhere else you must use the entire link, including the https:.

If you’re adding an email address to a page be sure to format your link with mailto to avoid creating broken links. For example, [example@gitlab.com](mailto:example@gitlab.com)

Identifiers

When there are repeated links across a single page, you can opt for using identifiers.

Place the identifiers at the end of the paragraph (or the section), arranging them in alphabetical order.

Markdown
[Text to display][identifier] will display a link.

[Another text][another-identifier] will do the same. Hover the mouse over it to see the title.

[This link] will do the same as well. It works as the identifier itself.

[This link][] (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not
contain a link.

<https://example.com> works too. Must be used for explicit links.

<!-- Identifiers, in alphabetical order -->

[another-identifier]: https://example.com "This example has a title"
[identifier]: http://example1.com
[this link]: http://example2.com
Output

Text to display will display a link.

Another text will do the same. Hover the mouse over it to see the title.

This link will do the same as well. It works as the identifier itself.

This link (same as above), has a second pair of empty brackets to indicate that the following parenthesis does not contain a link.

https://example.com works too. Must be used for explicit links.


Lists

Both ordered and unordered lists are very straightforward to produce. There are a few ways to produce the same results, but let’s stick with the following, again, to maintain some standards.

  1. Always start list items with a capital letter.
  2. Always leave a blank line before and after a list. Though this is currently not enforced (MD022).
  3. Begin a line with spaces (not tabs) to denote a nested sub-item. Items nested in lists should always align with the first character of the list item.
    1. For Unordered lists, use two spaces for each level of indentation. Though this is not currently enforced (MD007).
    2. For Ordered lists, use three spaces for each level of indentation.

Tip: don’t leave blank lines between the items, unless you have a reason to do so.

The Writing Style Guide recommends using ordered lists when you have multiple items, because Numbered lists are easier to reference during a discussion over bulleted lists.

See the Documentation Style Guide for other helpful tips.

Ordered lists

Ordered lists are pretty easy to create. Couldn’t be more intuitive:

Markdown
Paragraph:

1. Item one
   1. Sub item one
   2. Sub item two
   3. Sub item three
2. Item two
Output

Paragraph:

  1. Item one
    1. Sub item one
    2. Sub item two
    3. Sub item three
  2. Item two

To be practical and avoid errors on the numbers, use “1” for all the items. The markdown engine will output them in the correct order.

Markdown
Paragraph:

1. Item one
   1. Sub item one
   1. Sub item two
1. Item two
1. Item three

Output

Paragraph:

  1. Item one
    1. Sub item one
    2. Sub item two
  2. Item two
  3. Item three

Unordered lists

Unordered lists are very easy to create too:

Markdown
Paragraph:

- Item 1
- Item 2
- Item 3
  - Sub item 1
  - Sub item 2
- Item 4

Output

Paragraph:

  • Item 1
  • Item 2
  • Item 3
    • Sub item 1
    • Sub item 2
  • Item 4

Split lists

Let’s say, for some reason, you want to split a list in different parts. To do that, use the markup ^ to indicate the end of a list and the beginning of the next:

Markdown


- list one - item 1
- list one - item 2
  - sub item 1
  - sub item 2
- list one - item 3
^
- list two - item A
- list two - item B
^
- list three - item _i_
- list three - item _ii_

Output

  • list one - item 1
  • list one - item 2
    • sub item 1
    • sub item 2
  • list one - item 3
  • list two - item A
  • list two - item B
  • list three - item i
  • list three - item ii


Images

To insert images to your markdown file, use the markup ![ALT](/path/image.ext). The path can either be relative to the website, or a full URL for an external image. The supported formats are .png, .jpg, .gif. You might be able to use some .svg files too, depending on its structure.

![Semantic description of image](/images/path/to/folder/image.png "Image Title")

You can also use an identifier, as we do for links:

![Semantic description of image][identifier]

If you want to add a caption to your image, it’s easily achieved with:

![Semantic description of image](/images/path/to/folder/image.png)*My caption*

For clickable images, simply wrap the image markup into a link markup:

[![Semantic description of image](/images/path/to/folder/image.png "Hello World")*My caption*][handbook.gitlab.com]
Output

Diagrams

There are two ways to insert diagrams via Markdown:

  1. Mermaid
  2. PlantUML

Mermaid

See the examples in the GitLabm docs on how to use Mermaid. We have a number of Handbook-specific example in the Tools and Tips Section.

PlantUML

You can use PlantUML in Markdown blocks. For example:

Markdown

```plantuml
!define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.1.0
skinparam defaultTextAlignment center
!include ICONURL/common.puml
!include ICONURL/font-awesome-5/gitlab.puml
!include ICONURL/font-awesome-5/java.puml
!include ICONURL/font-awesome-5/rocket.puml
!include ICONURL/font-awesome/newspaper_o.puml
FA_NEWSPAPER_O(news,good news!,node) #White {
FA5_GITLAB(gitlab,GitLab.com,node) #White
FA5_JAVA(java,PlantUML,node) #White
FA5_ROCKET(rocket,Integrated,node) #White
}
gitlab ..> java
java ..> rocket

```

Output

!define ICONURL https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/v2.1.0
skinparam defaultTextAlignment center
!include ICONURL/common.puml
!include ICONURL/font-awesome-5/gitlab.puml
!include ICONURL/font-awesome-5/java.puml
!include ICONURL/font-awesome-5/rocket.puml
!include ICONURL/font-awesome/newspaper_o.puml
FA_NEWSPAPER_O(news,good news!,node) #White {
FA5_GITLAB(gitlab,GitLab.com,node) #White
FA5_JAVA(java,PlantUML,node) #White
FA5_ROCKET(rocket,Integrated,node) #White
}
gitlab ..> java
java ..> rocket


Videos

There are multiple ways of displaying videos:

  1. Using a shortcode.
  2. Within HTML5 <video> tags.
  3. Within <iframe> tags.

Display videos from YouTube

This method works for YouTube videos and any other embed video within an <iframe> tag.

  1. Copy the code below and paste it into your markdown file. Leave a blank line above and below it. Do NOT edit the code block (e.g., remove spaces - the video iframe may not render properly)
  2. Go the video URL you want to display
  3. Click on “Share”, then “Embed”
  4. Copy the <iframe> source (src) URL only, and paste it replacing the src below:

HTML
<!-- blank line -->
<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->

Output

Display local videos (HTML5)

This method works for any video uploaded to somewhere retrievable from the internet from a URL, or from a relative path like path/to/video.mp4.

  1. Read through the w3schools HTML5 video guide, or the MDN <video> guide
  2. Record or export the video in these three formats to achieve cross-browser and cross-device compatibility: .mp4, .ogg and .webm.
  3. Get the URL for your video
  4. Choose an image to use as a poster
  5. Copy the code below and paste it to your file
  6. Replace the src URLs for your video URLs

HTML

<!-- blank line -->
<figure class="video_container">
  <video controls="true" allowfullscreen="true" poster="path/to/poster_image.png">
    <source src="path/to/video.mp4" type="video/mp4">
    <source src="path/to/video.ogg" type="video/ogg">
    <source src="path/to/video.webm" type="video/webm">
  </video>
</figure>
<!-- blank line -->

Output

Display other videos

For any other videos, such as from Vimeo or Google Drive, grab the video iframe only, and proceed like we do for YouTube videos, wrapping the <iframe> within a <figure class="video_container">, for responsiveness. Copy and paste the code below, replacing only the iframe URL with your own:

HTML
<!-- blank line -->
<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"></iframe>
</figure>
<!-- blank line -->

Output

Display multiple videos

To display multiple videos on the same page, just repeat the figure code block where you want them to show up, replacing the video ID with the respective ID corresponding to your videos.

To display multiple videos in a sequence, just copy the figure code block and paste it as many times as necessary. Always leave a blank line between the blocks. Do NOT remove the spaces, otherwise your videos may not render properly.

<!-- blank line -->
<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"></iframe>
</figure>

<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"></iframe>
</figure>

<figure class="video_container">
  <iframe src="https://drive.google.com/file/d/0B6m34D8cFdpMZndKTlBRU0tmczg/preview" frameborder="0" allowfullscreen="true"></iframe>
</figure>
<!-- blank line -->

Tables

Tables for markdown are challenging. So, we have two possible approaches: use markdown whenever possible, but if you need pretty advanced table layouts, you are free to add them in HTML markup instead.

Markdown is not a replacement for HTML, or even close to it. (John Gruber

As explained by John Gruber, the creator of markdown, it was not created to replace HTML, so there are situations we can’t avoid using HTML. With complex tables, that’s the case.

The following table has a header (first line), then markup to define the desired alignment (dashes and colons), then the table body.

However you prepare your table, its design will depend upon the CSS styles defined for them.

| Default aligned | Left aligned | Center aligned  | Right aligned  |
|-----------------|:-------------|:---------------:|---------------:|
| First body part | Second cell  | Third cell      | fourth cell    |
| Second line     | foo          | **strong**      | baz            |
| Third line      | quux         | baz             | bar            |
Default aligned Left aligned Center aligned Right aligned
First body part Second cell Third cell fourth cell
Second line foo strong baz
Third line quux baz bar

The bars, spaces, and dashes were used symmetrically in the previous example to help future page developers if they need to edit the table’s contents. The symmetry isn’t required.

Some development tools can help you create your own complex table if you need to merge lines or columns, or if you require a more complex layout. This [table generator] may be able to help you do this.

To add a numbered list in a table cell, add a blank line between the heading and the table to render the table correctly. Otherwise, the text and formatting won’t appear.

To create more complex tables, you need to use HTML.


Collapse

A collapsed content section is used to hide information until a user chooses to reveal it with a click or tap on the summary text. The hidden content is revealed inline. For example, this code:

Markdown
{{% details summary="This is the summary text, click me to expand"%}}
This is the detailed text.

We can still use markdown and <strong>HTML</strong> in this block.

{{% /details %}}
Output

This is the summary text, click me to expand

This is the detailed text.

We can still use markdown and HTML in this block.

The GitLab handbook also supports nested details sections.

Markdown
{{% details summary="First level collapsible item" %}}
**Lorem ipsum dolor sit amet...**
{{% details summary="Second level collapsible item" %}}
_Sed ut perspiciatis unde omnis iste natus..._
{{% /details %}}
{{% /details %}}
Output

First level collapsible item

Lorem ipsum dolor sit amet…

Second level collapsible item

Sed ut perspiciatis unde omnis iste natus…


Code blocks

There are a few options for displaying code blocks with Markdown. Most of them use backticks `.

Note: While indented code formatting is common, we enforced “fenced” for code blocks (MD046).

In-line

There is the in-line code block. Used this to reference very short bits of code, filenames and folder paths, and programming symbols and objects in a bit of text. The whole line including the code block should read fluidly.

Markdown
This is an  `in-line` code block.
Output

This is an in-line code block.

Fenced with syntax highlighting

This is the most common code block you will encounter and use. You can use this to share whole sections of code within a markdown document. The additional syntax highlighting makes the code easier to read and understand. The highlight function supports a large number of languages including Ruby, Python, Rust, Swift, etc.

Markdown
```ruby
def hello
   puts "Hello world!"
end
```
Output

def hello
   puts "Hello world!"
end

Fenced

There are times where you don’t want syntax highlighting either because the language isn’t supported or because you feel the syntax highlighting distracts from the content. To achieve this you can just skip specifying the language to get a code block without highlighting. This technique is also useful for Markdown engines which don’t support any form of syntax highlighting.

Markdown
```
def hello
   puts "Hello world!"
end

```
Output

def hello
   puts "Hello world!"
end

In lists

Indent the text of each item in 3 white spaces. Leave blank lines between the code block and the list items, and ident the code block in 5 white spaces:

Markdown
1.   Item 1
1.   Item 2

     ```ruby
     def hello
        puts "Hello world!"
     end
     ```

1.   Item 3
Output

  1. Item 1
  2. Item 2
    def hello
       puts "Hello world!"
    end
    
  3. Item 3


Blockquotes

Blockquotes are good resources to mentioning someone else’s quotes, like we did just above. Also, can be used to emphasize a sentence or a small paragraph.

Markdown

> This is a blockquote.
>     On multiple lines.
That may be lazy.
>
> This is the second paragraph.

---

> This is a paragraph.
>
> > A nested blockquote.
>
> ### Headers work
>
> * lists too
>
> and all other block-level **elements**.
>
> Even code blocks:
>
> ```ruby
> def hello
>   puts "Hello world!"
> end
> ```
Output

This is a blockquote. On multiple lines. That may be lazy.

This is the second paragraph.


This is a paragraph.

A nested blockquote.

Headers work

  • lists too

and all other block-level elements.

Even a code block:

def hello
  puts "Hello world!"
end


Comments

There are two types of comment which can be used. The first allows you to leave comments in a markdown file which can only be viewed in the repo and are not rendered to HTML or included in a pages source. The second type is a standard HTML comment which will be included in the pages source.

Markdown comments

See comments shortcode.

HTML Markup comments

It is also possible to use HTML comments. These differ in that they are also included in the rendered pages source.

Markdown

This is a paragraph <!-- This is accepted as a comment too --> ... paragraph continues here.
Output

This is a paragraph … paragraph continues here.

Output HTML
<p>This is a paragraph <!-- This is accepted as a comment too -->paragraph continues here.</p>

Anchors

Typically you shouldn’t need anchors as well structured documents with headings should prove a good route to linking to text you want may want to reference on another page. All headings act as anchors on a page. However there maybe times when you do need to drop an anchor in a long bit of text. You can do this in one of two ways. The first is the shortcode method and the other is with HTML.

Shortcode Anchors

This is the preferred method of handling anchors in the handbook. This small shortcode will drop an anchor in a page which you can reference from the same page or another page. The text in quote marks is the name of anchor you’ll use when linking to it.

Markdown
{{% a "hello-world" %}} Anchors are invisible elements
Output

Anchors are invisible elements

Output HTML
<a name="hello-world"></a> Anchors are invisible elements

HTML Anchors

One of the more powerful features of using Markdown is the ability to mix HTML and Markdown in the same document. With this in mind it is also possible to use normal HTML to create an anchor in a page. This is the method you need to use when adding anchors to markdown documents not in the GitLab Handbook.

Markdown
<a name="goodbye-world"></a> Anchors are invisible elements
Output

Anchors are invisible elements


Emoji and Font Awesome

Hugo and Docsy provide support for using both Emojis and Font Awesome to provide icons and simple graphics to spice up your content.

Emojis

To insert emojis in to content you can use the same syntax as you find on GitLab and Slack. Use a : followed by the name of the emoji followed by another :. Its also possible to look up emojis on the ‘Emoji Cheat Sheet’.

Note: When copying from the cheatsheet it includes the colons for you.

Markdown

I :‌orange_heart: GitLab

Output

I :orange_heart: GitLab

Font Awesome

Font Awesome provides over 2000 free to use and open source glyphs and icons which can be embedded into handbook content to visually spice things up. The easiest way to use Font Awesome is to copy the html for the glyph directly from the Font Awesome Icon gallary and paste it directly in to your content.

Markdown
<i class="fa-brands fa-gitlab fa-2xl"></i>
Output

Splash of color

It is possible to add a splash of color to Font Awesome icons by adding -text-<color> to the end of the class definition. Where it says color you can replace this with:

Named colors:

-text-blue -text-indigo -text-purple

-text-pink -text-red -text-orange

-text-yellow -text-green -text-teal

-text-cyan -text-gray -text-black

Theme colors:

-text-primary -text-secondary -text-success

-text-info -text-danger -text-warning

-text-light -text-dark

Note: More color variations are available than this. You can find these by looking at the Bootstrap Documentation

Markdown
<i class="fa-brands fa-gitlab fa-2xl -text-primary"></i>
Output


Colorful sections

See panels shortcode.


Embed documents

It’s easy to embed Google Docs, Sheets, Slides, and pretty much everything that provides an iframe to use with. The only thing you need to do is use the following code inside your markdown file and replace the iframe from the document you want to embed:

<iframe IFRAME CONTENT></iframe>

Google products

For Google products, with your document opened, click File -> Publish to the web. For example, here’s what Google sheets will look like:

Google Sheets - File - Publish to the web

Choose Embed, check your settings, click on Publish and copy the <iframe>. Then go to your markdown file and wrap the iframe into a {{< gdoc >}} short code. The shortcode makes the iframes the right size on the page and allows them to be resized by the user.

Google Sheets

Let’s exemplify with this [simple spreadsheet]. Follow the info above to find the iframe:

Google Sheets - Embed iframe

Copy the code below and paste to your markdown file (leave a blank line above and below it). Then replace the <iframe> with your own:

Markdown
{{< gdoc >}}
<iframe src="https://docs.google.com/spreadsheets/d/1jAnvYpRmNu8BISIrkYGTLolOTmlCoKLbuHVWzCXJSY4/pubhtml?widget=true&amp;headers=false"></iframe>
{{< /gdoc >}}
Output

Google Slides

Let’s exemplify with this GitLab slide deck. Follow the steps above to find the iframe:

Google Slides - Embed iframe

Copy the code below and paste to your markdown file (leave a blank line above and below it). Then replace the <iframe> with your own:

Markdown
{{< gdoc >}}
<iframe src="https://docs.google.com/presentation/d/e/2PACX-1vS_iuMXnp61wlo4amm5nvHr4Ir8VUzisJSBsr7YEL7fKWAiT-9bmehyngtb9TYaFEsFnRokCyIXwsvY/embed?start=false&loop=false&delayms=3000"
frameborder="0" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
{{</ gdoc >}}
Output

Google Docs

If you need to embed it anyway, follow the same instructions and the same logic as we presented for Google Sheets and Slides, wrapping the <iframe> with a {{< gdoc >}} shortcode:

Markdown
{{< gdoc >}}
<iframe src="https://docs.google.com/document/d/1mHhOhvvrz7xgUPyn5VWCNuKgew5MRRGZp761B9prPqs/pub?embedded=true"></iframe>
{{< /gdoc >}}
Output


Embed Tweets

X/Twitter changed its usage policy, and might add rate limits. Sometimes, tweets cannot be loaded when embedded, and fail CI/CD builds or the deployed handbook (see the issue discussion). Create a screenshot of the tweet instead, and upload the image into the handbook.


Embed GitLab Snippets

To embed GitLab Snippets to a markdown file, copy the embed code from your public snippet and paste it in the file.

Markdown
<!-- leave a blank line here -->
<script src="https://gitlab.com/gitlab-org/gitlab-ce/snippets/1717978.js"></script>
<!-- leave a blank line here -->
Output


Line length

We do not enforce a line length (MD013).

Markdown Editors

Please use the editors available on GitLab.com, one of the following code editors, or your preferred code editor to write in markdown.

It is not recommended writing your document in a regular text editor like Google Docs, Microsoft Word, or macOS’s Pages, then copy-pasting to markdown, as it most likely will bring some characters with a different encoding (non UTF-8), which will cause the markdown to not render correctly.

In case you don’t have a choice and need to import a text already written in a text editor, paste it to your markdown file using command+shift+V on a Mac, or control+shift+V on Windows or Linux. You might minimize the cause of trouble by pasting without format. But yet, is not guaranteed it is going to work, so double check your output.

If the document was in Google Docs, you can install the Docs to Markdown add-on, which helps convert the Google Docs to markdown. You’ll likely need to make minor updates or edits to the markdown that the add-on generates.

Editors Available on GitLab.com

Regular Code Editors

Markdown editors (type and preview simultaneously)

  • Markdown editors for Mac: [MacDown], [iA Writer], [Ulysses]
  • In-browser markdown editor: [StackEdit]
  • Markdown Tables Generator

If you’re not used to writing markdown, these editors can be helpful. Many editors offer realtime previews and while these previews may not be exactly the same as the final result they can be a very good approximation, which gives you a good idea of what the output will be while you type.

[StackEdit] is awesome too, you can work on a markdown file even if you’re away from your computer, or out of resources. It works from every major browser and automatically saves your work to Google Drive.

Do you want a simple way of copying a hyperlink title and address in markdown? The Format Link extension offers a quick and easy way to do this, along with allowing you to customize any number of other formats. View detailed instructions and examples.

If you’re looking for just the ability to copy something as markdown, try these Firefox add-ons or Chrome extensions.


Complementary Notes

  • Words must be separated by one single space only. Do not leave more blank spaces than the necessary, they can render differently than expected and can cause other issues.

  • Do not leave blank spaces at the end of sentences.

  • Always leave a blank line between block-level markup elements, except between list items. Example:

    --- (markup for horizontal line)
    <!-- blank line -->
    Paragraph.
    <!-- blank line -->
    Do not leave blank lines within list items:
    <!-- blank line -->
    - Item 1
    - Item 2
    - Item 3
    
  • As explained above, do not skip headings. Always do h1 → h2 → h3 → h4. Never h2 → h4.

  • Prefer short titles and headings. Do not punctuate them (unless they require a question mark or an exclamation).

  • Try not to punctuate list items, but if you do, be consistent and do that throughout the list.

  • If you have to mention a non-clickable URL, prefer using backticks: http://an-example.com.

  • To add fancy emojis to your file, click control+cmd+space on your Mac and check the ⭐️ magic ⭐ or use a website like Emoji Finder. Do not overuse them, please!

  • If you are confused about any markup that you’ve found in this file, you can check its raw file for reference, where you’ll be able to see exactly how everything was written to produce the results you are seeing on this page.


More

Anything else you know of and is not described here? Any new magic? Any trick? Please contribute!