Handbook Markdown Guide

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

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:

1
2
3
4
5

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

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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

1
2
3
4
5

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

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:

1
2
3
4
5
6

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

The GitLab handbook also supports nested details sections.

1
2
3
4
5
6

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

Code blocks

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

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.

1

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.

1
2
3
4
5

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

1
2
3

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.

1
2
3
4
5
6

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

```

def hello
   puts "Hello world!"
end

Indented

It is also possible to get a code block to render by putting 4 space in front of the code you want to render as a code block. This is quicker to do but it does not let you specify the languague for syntax highlighting.

1
2
3

    def hello
      puts "Hello world!"
    end

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

1.   Item 1
1.   Item 2

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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

Notes and alerts

There are two types of notes and an alert. The classic small GitLab note and the big callout notes which you see using this guide. GitLab classic notes are smaller and can be used to mention something out of context. Additionally there are warning and note style blocks where you need to draw the users attention to something out of context.

GitLab classic notes

1
2
3
4
5

This is a regular paragraph.

{{< note >}}
a note is something that needs to be mentioned but is apart from the context.
{{< /note >}}

Alerts

1
2
3

{{% alert title="Warning" color="warning" %}}
This is a warning or an alert.  You can change set the title to what you need.
{{% /alert %}}

Danger

1
2
3

{{% alert title="Danger" color="danger" %}}
This is a danger alert.  You can change set the title to what you need.
{{% /alert %}}

Callout notes

1
2
3
4
5

This is a regular paragraph.

{{% alert title="Note" color="primary" %}}
This is an out of context note that you want to draw a users attention to.
{{% /alert %}}

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 Comment

These comments are only viewable when viewing the pages source code and are removed before the page is rendered.

1
2
3
4
5
6

This is a paragraph.
{{< comment >}}
This is a comment which is
completely ignored.
{{< /comment >}}
Next paragraph is here.

1
2

<p>This is a paragraph.</p>
<p>Next paragraph is here.</p>

HTML Markup comments

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

1
2

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

1
2

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

1

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

1

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

1

<a name="goodbye-world"></a> 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’.

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.

1

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

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

1

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

Colorful sections

To add notes and warning blocks into colorful boxes we have provided a shortcode for a panel. This is a lot like the docsy card shortcode but takes up the whole width of the content area and can make use of custom header, body and footer colors.

Colorful sections are applied for very specific purposes and must not be overused.

Use panels when your description contains more than one paragraph, or a long paragraph. For single and short paragraphs, use alert boxes instead.

Copy paste the following code according to what you want to present to the user and replace only the description. The available colors are any of the named colors below:

blue indigo purple

pink red orange

yellow green teal

cyan gray black

primary secondary success

info danger warning

light dark

Additional Information

Use the following code for important notes and additional information:

1
2
3

{{< panel header="**Note**" header-bg="blue" >}}
NOTE DESCRIPTION
{{< /panel >}}

Warnings

Use the following code for warnings, like information that may have a different result if not used correctly:

1
2
3

{{< panel header="**Warning**" header-bg="warning" >}}
WARNING DESCRIPTION
{{< /panel >}}

Danger

Use the following code for crucial warnings, like commands that result in loss of data:

1
2
3

{{< panel header="**Danger**" header-bg="danger" >}}
DANGER DESCRIPTION
{{< /panel >}}

Do’s and Don’ts

You can use the combination of green and red panels or alert boxes for “Do’s and Don’ts”:

1
2
3
4
5
6

{{< panel header="**Do's**" header-bg="success" >}}
THINGS TO DO
{{< /panel >}}
{{< panel header="**Don'ts**" header-bg="danger" >}}
THINGS NOT TO DO
{{< /panel >}}

Its also possible to wrap panels in a card pane so that they render next to each other.

1
2
3
4
5
6
7
8
9

{{< cardpane >}}
{{< panel header="**Do's**" header-bg="success" >}}
THINGS TO DO
{{< /panel >}}
{{< panel header="**Don'ts**" header-bg="danger" >}}
THINGS NOT TO DO
{{< /panel >}}
{{< /cardpane >}}

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:

1

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

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:

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:

1
2
3

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

Google Slides

Let’s exemplify with this GitLab slide deck. Follow the steps above to find the 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:

1
2
3
4

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

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:

1
2
3

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

SlideShare

To embed from SlideShare, go to the document you want to embed and hit the Share button located below the slides. Copy the code under Embed and place it inside the {{< gdoc >}} shortcode.

For example, let’s say we wanted to include the slides from Ivan’s talk on GitLab Pages. Copying the embed code and stripping everything else except from the iframe, would result in this:

1
2
3
4
5

{{< gdoc >}}
<iframe src="//www.slideshare.net/slideshow/embed_code/key/EixD8OUMBX65Jy" width="595" height="485" frameborder="0"
marginwidth="0" marginheight="0" scrolling="no"
style="border:1px solid #CCC; border-width:1px; margin-bottom:5px; max-width: 100%;" allowfullscreen></iframe>
{{</gdoc>}}

Embed Tweets

To embed a tweet you just need to grab the users name (without the @) and the ID of the tweet. You can get both from the tweets link url.

twitter.com/gitlab/status/1615757252928864273

The first highlighted part is the user name and the last bit is the tweet id. Now just wrap it in a {{< tweet >}} shortcode and Hugo will do the rest.

1

{{< tweet user="gitlab" id="1615757252928864273" >}}

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.

1
2
3

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

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

• Web IDE
• Web Editor

Regular Code Editors

• Visual Studio Code
• Sublime Text
• BBEdit
• Vim
• NeoVim
• Nova by Panic

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:

  1 2 3 4 5 6 7 8 9

  ---- (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!