Markdown Guide

https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#headings

For our Blog, everything in this guide can be applied. Read through the Blog Style Guidelines and the Professional Writing Techniques for further information.


## Heading h2

### Heading h3

#### Heading h4

Output

Notes:

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.

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

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, jump a line between any heading and its subsequent paragraph.

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.

It is a best practice to write each a paragraph on a single line. Don't put line breaks at the end of each sentence, and don't break up lines at a certain character limit. It is very difficult to review and edit copy with artificial lines breaks.

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.

We usually break the lines within paragraphs to facilitate reviews. 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>.


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.

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:

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

Emphasis: bold and italic

To display bold or italic text, wrap it in stars or underlines:

Links

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.

Important notes:

Don't take it as a restrictive rule, but avoid using meaningless text for links as "this article" or "read here." The link text should be meaningful even if taken out of context; this makes the links more useful and accessible for people using screen readers.

We'd rather use inline links, such as [Text to display](link), as they are easier to maintain.

Use relative links when referring to links found on about.gitlab.com. For example, a link to our blog handbook should look like this /handbook/marketing/blog/ and not this https://about.gitlab.com/handbook/marketing/blog/. Remove everything from the https through about.gitlab.com, but retain the forward slash after .com.

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

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)

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.

Note:

Identifiers are not case sensitive. They can be single words as [link] or [multiple words too].

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

Always use 3 blank spaces to indent a nested list (to create sub items).

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

Important: always leave a blank line between the paragraph or heading and the subsequent list! If you don't, the list will not render.

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

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.

Unordered lists are very easy to create too:

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:

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.

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

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

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

My caption

Important notes:

All images must be placed under /source/images/, in an appropriate directory. Only screenshots and public domain images are permitted.

The text inside the square brackets is an image attribute called ALT, which stands for alternative text. Including descriptive alt text helps maintain accessibility for every visitor and should always be included with an image. When you add alt text be sure to describe the content and function of an image. In addition to the accessibility benefits, ALT is useful for SEO, and it is displayed when, for some reason, that image is not loaded by the browser.

For the same reasons, the image must contain a name related to it. Example: instead of image-01.jpg, name it black-dog.jpg, if it's a photo of a black dog.

It's also recommendable adding an image title, as the "Hello World" exemplified above.

There are two ways of displaying videos: within HTML5 <video> tags and within <iframe> tags.

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

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)

Go the video URL you want to display

Click on "Share", then "Embed"

Copy the <iframe> source (src) URL only, and paste it replacing the src below:

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.

Record or export the video in these three formats to achieve cross-browser and cross-device compatibility: .mp4, .ogg and .webm.

Get the URL for your video

Choose an image to use as a poster

Copy the code below and paste it to your file

Replace the src URLs for your video URLs

Note: in case you don't have all formats recommended by w3schools, you can use just one of them, but your video most likely won't be supported in all devices and browsers. The video above (.mp4 only) worked on Mozilla Firefox for OS X, Android, and Windows, and on Chrome for Android and for Windows. But it may not work on other devices/browser, such as Chrome for OS X and iOS, or Safari. In fact, the best option is using YouTube or Vimeo embed videos in <iframe> tags.

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:

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.

Table of Contents (ToC)

With kramdown, creating a Table of Contents is the easiest thing ever! The automatic ToC will include every heading in the document, unless you don't want it to be included. You do not need to add anchors individually to every title. This is an automated process.

As always, leave a blank line before and after the markup. Note that there are four dashes beginning and closing the block, which is not required, but recommendable for keeping the same standards throughout about.GitLab.com.

The heading "On this page" can be adapted to your case, e.g., "In this tutorial", or "In this guide", etc. It's not required either, but recommended.

The markup {:.no_toc} is used every time you don't want to include a heading into the ToC. Just add it right below the heading, and it won't be included into the ToC. In fact no_toc is a custom class, as described later in this guide.

The output ToC can be found at the very beginning of this page.

Alternatively, you can use ordered ToC too, displaying numbers at the beginning of the list. Just use the markup for ordered lists and kramdown will be smart enough to understand what you want:

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. You can go ahead and add separators to create subsequent table bodies.

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

The last markup {: .custom-class #custom-id} can be used in case you want to attribute a custom class and/or a custom ID to the <table> element.

Certain tools can help you to create your own complex table if you need merging lines or columns, and more advanced layouts. This is a Table Generator that might help you out.

Note that the bars, spaces, and dashes were used symmetrically above just for providing a nice view of the table markup. The symmetry is not required.

Read through the kramdown syntax guide on tables for further information.

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

This is an `in-line` code block.

Fenced Highlighted

Add 4 white spaces before every line:

Indented Highlighted

Add 4 white spaces before every line. This is used when you want to display a code block within a code block.

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:

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.

Notes

Markdown markup

Regular HTML markup

Anchors

Add an anchor anywhere with:

Or simply use an ID:

Yes, we can use fancy Font Awesome icons too.

Regular

And you can go further, such as the following.

Styled

When doing something like this to a heading, it's important give it a custom ID (e.g., {: #puzzle}), otherwise the one automatically created by kramdown will sound very awkward.

The class fa-fw is used when you want to display the icons as a list. They will be aligned, as well as the text right beside them.

See live examples on this post, where the icons are used to illustrate the text.

Classes, IDs, and attributes

Defining CSS classes, and elements IDs and attributes with markdown is definitely something unusual (kramdown magic!).

But yes, if you know how to use it, you'll love it! Check how easy it is to do that with kramdown:

The CSS class called shadow should be used when your image edges are not clearly defined. This happens when it has a white background or when it's a screenshot with text (for example, a screenshot of our user interface). For example, this image can be mistaken as part of the text:

Now, if you apply the class shadow to the image, it's discreetly highlighted from the text:

To do that, apply the class directly to the image by adding the markup {: .shadow} right after the image markup:

As previously explained, you can add the class note to paragraphs that you don't want to call attention to:

Note: this is something I don't want to call attention to.

Markup:

Add a custom class to a heading or paragraph using the following special classes.

GitLab Orange

Markup:

GitLab Purple

Markup:

By default, the text will always be aligned to the left. You have a few options to customize it with custom classes:

Center: .text-center

Right: .text-right

Justify: .text-justify

For demonstrations purposes, they are aligned in an alert box, but this can be applied to regular paragraphs and headings.

Align to the center

Center-aligned

Alert box markup:

Paragraph markup:

Heading markup:

Align to the right

Right-aligned

Justify

Justified

Mix HTML + Markdown Markup

Mixing HTML markup with markdown is something almost "unthinkable" to someone used to regular markdown. And it's all over this document!

Use the following markup at the beginning of your document:

And feel free to mix everything up:

You can close the markup parser tag at any point, if you want to:

Colorful sections

To add notes and warning blocks into colorful boxes, we are making use of Bootstrap's panel blocks and alert boxes.

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.

When using panels, make sure to add the HTML parser markup to the beginning of your document's body: {::options parse_block_html="true" /}.

Copy paste the following code according to what you want to present to the user and replace only the description. The available colors are: blue (info), green (success), amber (warning) and red (danger), as follows.

Use the following code for important notes and additional information:

To apply to a single paragraph, use an alert box:

Blue panels render like:

And blue alert boxes render like:

My important paragraph.

If you want the text inside the alert box to be blue as well, we need to apply custom styles to the markdown document. They will override the existing ones. Add the following style tag to the end of your file.

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

To apply to a single paragraph, use an alert box:

Amber panels render like:

And amber alert boxes render like:

My warning paragraph.

If you want the text inside the alert box to be amber as well, we need to apply custom styles to the markdown document. They will override the existing ones. Add the following style tag to the end of your file.

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

To apply to a single paragraph, use an alert box:

Red panels render like:

And red alert boxes render like:

My danger paragraph.

If you want the text inside the alert box to be red as well, we need to apply custom styles to the markdown document. They will override the existing ones. Add the following style tag to the end of your file.

You can use the combination of green and red panels or alert boxes for "Do's and "Don'ts":

or, use an alert box:

Not to do:

or, use an alert box:

By doing so, the green panels for "DO'S" will look like:

or, if you chose an alert box:

TO DO.

If you want the text inside the alert box to be green as well, we need to apply custom styles to the markdown document. They will override the existing ones. Add the following style tag to the end of your file.

And for your "DON'TS" within red panels will look like:

or, if you chose a red alert box:

NOT TO DO.

All the previously mentioned alert boxes and panels are available by default by Bootstrap. If we want them in a different color, we need custom styles. At about.GitLab.com, we can use the orange and the purple one, as follows.

When using panels, don't forget to add to the beginning of your file the HTML parser markup to be able to mix HMTL + Markdown: {::options parse_block_html="true" /}.

Panel block markup:

GitLab Orange Alert Box

My text in an orange box.

Box block markup:

GitLab Purple Alert Panel

Panel block markup:

GitLab Purple Alert Box

My text in an purple box.

Box block markup:

GitLab Webcast Alert Box

To be used in a CTA for webcast announcement in blog posts. You can use it for other purposes as well. Use it together with the HMTL parser:

Styles

Yes, guess what?

This:

Plus:

Equals to:

And yes, the <style> tag is in this very markdown file. Believe it or not!

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:

For Google products, with your document opened, click File -> Publish to the web. For example here's how 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 <figure> tag with the responsive video_container class, as shown in the beginning.

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:

Let's exemplify with this GitLab deck template. 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:

Embedding Google Docs is not a recommended practice. Prefer converting your document content to markdown instead. 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 <figure> tag:

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

Be careful to only include the iframe content and strip anything else. SlideShare will also add some other information in the embed code which you will have to remove, otherwise the markdown page will be broken.

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:

You can safely omit the <figure> tag since SlideShare's widget is already responsive, but we are showing this that way in order to be consistent with the rest of the handbook.

1 of 28 View on SlideShare Like this slideshow? Why not share!

AB Testing chez M6Web by Fabien de Saint pern 1631 views

Embed Tweets

To add tweets to markdown, copy both <blockquote> and <script> tags from the twitter post and paste it into your file. To make it look much nicer, wrap the script into a div.center (created for this specific purpose).

Important: if you used the HTML parser in your post or page, you'll need to set it to false before the div.

Markup:

For more than one Tweet, copy and paste all the code blocks from Twitter into one div.center:

Embed Instagram posts

To embed posts from Instagram, begin by pasting the following code into your file:

Then go to the relevant Instagram post on the web: Go to the post URL if you have it, or you can search for the username on Instagram.com, visit their profile, and then click the post to expand it. Click the more […] button and select "Embed."

Copy the code and paste it below <div align="center">.

Add </div> after the code you pasted from Instagram.

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.

Markup:

Renders:

Markdown Editors

Please use one of the following code editors to write in markdown, or another code editor of your preference.

It is not recommend writing your document in a regular text editor, 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 HTML output.

Regular Code Editors

Markdown editors (type and preview simultaneously)

In-browser markdown editor: StackEdit

If you're not used to writing markdown, those editors can be helpful. Check a screenshot below of a file being edited on Mou. On your left, there's the markdown markup you're writing, and on your right, a preview of the output. The preview won't be exactly as the final result, but it's a very good approximation, which gives you a good idea on what you're doing while you type.

Mou for Mac - Markdown Preview

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.

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

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

Markdown Guide | GitLab

Paragraphs, breaks, and horizontal lines

Emphasis: bold and italic

Links

Images

Display local videos (HTML5)

Table of Contents (ToC)

Tables

Blockquotes

Notes

Anchors

Classes, IDs, and attributes

Mix HTML + Markdown Markup

Colorful sections

GitLab Orange Alert Box

GitLab Purple Alert Panel

GitLab Purple Alert Box

GitLab Webcast Alert Box

Styles

Embed Tweets

Embed Instagram posts

Embed GitLab Snippets

Markdown Editors

More