Markdown Guide


Welcome to the Markdown Kramdown Style Guide for about.GitLab.com


On this page


Markdown Style Guide for about.GitLab.com

This website was generated by Middleman, 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 about.GitLab.com, we use Kramdown, which is an advanced markdown engine with a lot of interesting features that most of the other engines don't have.

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. Not all of them run with Kramdown, so the markup will not behave equally "GitLabwide". For GitLab.com, GitLab CE and GitLab EE text areas, the markdown engine is currently Redcarpet. Here you can find the markdown style guide for them.

This guide has been made to make it easier for everyone to use Kramdown features and save a lot of time writing content for about.GitLab.com, including handbook pages, website pages, blog posts and everything else within the project www-GitLab-com.

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

Blog

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


Headings

## Heading h2

### Heading h3

#### Heading h4

Output

Heading h2

Heading h3

Heading h4

Notes:


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. But, if you leave a blank line between them, they will split into two paragraphs.

Regular paragraphs and automatic join

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.

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

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:

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 4 for standard. Leave blank lines after and before it:

Text
<!-- blank line -->
----
<!-- blank line -->
Text

Output

Text


Text


Emphasis: bold and italic

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

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

Output

This is bold and this is italic.


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.

Place the identifiers at the end of the file, arrange them in alphabetical order. You can group them in different categories, if that's the case. Check this post for reference. It's important to organize the links in certain order to be easy and quick to find them for both the author and the reviewers.

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

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

... (page content) ...

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

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

… (page content) …

Important notes:


Lists

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

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

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 markdwon engine will output them in the correct order.

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:

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:

- 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 A
^
- 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 A
  • 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.

![An awesome example image](/images/path/to/folder/image.png "Image Title")

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

![An awesome example image][identifier]

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

![An awesome example image](/images/path/to/folder/image.png)*My caption*

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

[![An awesome example image](/images/path/to/folder/image.png "Hello World")*My caption*][about.gitlab.com]

Output

Important notes:


Videos

There are two ways of displaying videos: within HTML5 <video> tags and 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
  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:
<!-- blank line -->
<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/enMumwvLAug" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->

Output

Display other videos

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

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.


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.

----

## On this page
{:.no_toc}

- TOC
{:toc}

----

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 through about.GitLab.com.

The heading "On this page" can be adapted to your case, e.g., "On this tutorial", or "On 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:

1. TOC
{:toc}

Tables

Tables for markdown are challenging. So, we have two possible approaches: use markdown markup 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 has not been created to replace HTML, so there are situations we can't run from 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 forward and add a separator to create subsequent table bodies.

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

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

| 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            |
|-----------------+--------------+-----------------+----------------|
| Second body     |              |                 |                |
| 2nd line        |              |                 |                |
|-----------------+--------------+-----------------+----------------|
| Third body      |              |                 | Foo            |
{: .custom-class #custom-id}

Output

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
Second body      
2nd line   Hello World  
Third body     Foo

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


Code blocks

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

In-line

This is an `in-line` code block.

Output

In-line

This is an in-line code block.

Fenced

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

Fenced Highlighted

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

or

```
def hello
   puts "Hello world!"
end
```
{: .language-ruby}

Output

Fenced

def hello
   puts "Hello world!"
end

Fenced Highlighted

def hello
   puts "Hello world!"
end

or

def hello
   puts "Hello world!"
end

Indented

Add 4 white spaces before every line:

    def hello
       puts "Hello world!"
    end

Indented Highlighted

    def hello
       puts "Hello world!"
    end
{: .language-ruby}

Output

Indented

def hello
   puts "Hello world!"
end

Indented Highlighted

def hello
   puts "Hello world!"
end

Nested

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

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

Output

Nested

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

> 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:
>
>      def hello
>        puts "Hello world!"
>      end
> {: .language-ruby}

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

Notes

This is a regular paragraph.

**Note:** a note is something that needs to be mentioned but is apart from the context.
{: .note}

Output

This is a regular paragraph.

Note: a note is something that needs to be mentioned but is apart from the context.


Comments

Markdown markup

This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.

Regular HTML markup

<!-- This is accepted as a comment too -->

Output

This is a paragraph … paragraph continues here.


Anchors

Add an anchor anywhere with:

[](){: name="hello-world"}

Some text

Or simply use an ID:

Some text
{: #hello-world}

Font Awesome

Yes, we can use fancy Font Awesome icons too.

Regular

### <i class="fa fa-puzzle-piece" aria-hidden="true"></i> Puzzle Icon
{: #puzzle}

And you can go further, such as the following.

Styled

### <i class="fa fa-puzzle-piece fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Purple Puzzle Icon
{: #puzzle-purple}

### <i class="fa fa-gitlab fa-fw" style="color:rgb(252,109,38); font-size:.85em" aria-hidden="true"></i> Orange GitLab Tanuki
{: #tanuki-orange}

Output

Regular

Puzzle Icon


Styled

Purple GitLab Tanuki

Orange GitLab Tanuki

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:

Paragraph
{: .class .class-1 .class-2}

Paragraph
{: #custom-id}

Paragraph
{: .class .class-1 #custom-id-1}

## Heading
{: .class .class-1 #custom-id-2}

Paragraph
{: .class #custom-id-3 style="padding-top:0" key="value"}

## Heading {#hello}

List:

- {: .class} List item with custom class
- {:#id} List item with custom id

To a [link]{: #link}, in-line.

This is a [link][google-es]{:hreflang="es"} in Spanish.

[link]: https://google.com
[google-es]: https://google.es

Output

Paragraph

Paragraph

Paragraph

Heading

Paragraph

Heading

List:

  • List item with custom class
  • List item with custom id

To a link, in-line.

This is a link in Spanish.

Special classes

Shadow

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:

text screenshot

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

text screenshot with box shadow

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

![image alternative text](/path/to/image.png){: .shadow}

Note

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:

**Note:** this is something I don't want to call attention to.
{: .note}

Colors

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

GitLab Orange

GitLab Orange Heading

Markup:

### GitLab Orange Heading
{: .gitlab-orange}

GitLab Purple

GitLab Purple Heading

Markup:

### GitLab Purple Heading
{: .gitlab-purple}

Text Align

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

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:

Center-aligned
{: .alert .alert-info .text-center}

Paragraph markup:

Center-aligned
{: .text-center}

Heading markup:

### Center-aligned
{: .text-center}

Align to the right

Right-aligned

Right-aligned
{: .alert .alert-info .text-right}

Justify

Justified

Justified
{: .alert .alert-info .text-justify}

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:

{::options parse_block_html="true" /}

And feel free to mix everything up:

Something in **markdown**.

<p>Then an HTML tag with crazy **markup** _all over_ the place!</p>

Output

Something in markdown.

Then an HTML tag with crazy markup all over the place!

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

{::options parse_block_html="false" /}

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.

Additional Information

Use the following code for important notes and additional information:

<div class="panel panel-info">
**Note**
{: .panel-heading}
<div class="panel-body">

NOTE DESCRIPTION

</div>
</div>

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

My important paragraph.
{: .alert .alert-info}

Blue panels render like:

Note

INFO DESCRIPTION

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.

<style>
.alert-info {
  color: rgb(49,112,143) !important;
}
</style>

Warnings

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

<div class="panel panel-warning">
**Warning**
{: .panel-heading}
<div class="panel-body">

WARNING DESCRIPTION

</div>
</div>

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

My warning paragraph.
{: .alert .alert-warning}

Amber panels render like:

Warning

WARNING DESCRIPTION

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.

<style>
.alert-warning {
  color: rgb(138,109,59) !important;
}
</style>

Danger

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

<div class="panel panel-danger">
**Danger**
{: .panel-heading}
<div class="panel-body">

DANGER DESCRIPTION

</div>
</div>

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

My danger paragraph.
{: .alert .alert-danger}

Red panels render like:

Danger

DANGER DESCRIPTION

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.

<style>
.alert-danger {
  color: rgb(169,68,66) !important;
}
</style>

Do's and Don'ts

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

<div class="panel panel-success">
**Do's**
{: .panel-heading}
<div class="panel-body">

THINGS TO DO

</div>
</div>

or, use an alert box:

TO DO.
{: .alert .alert-success}

Not to do:

<div class="panel panel-danger">
**Don'ts**
{: .panel-heading}
<div class="panel-body">

THINGS NOT TO DO

</div>
</div>

or, use an alert box:

NOT TO DO.
{: .alert .alert-danger}

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

Do's

THINGS TO DO

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.

<style>
.alert-green {
  color: rgb(60,118,61) !important;
}
</style>

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

Don'ts

THINGS NOT TO DO

or, if you chose a red alert box:

NOT TO DO.

Custom alert panels and alert boxes

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" /}.

GitLab Orange Alert Panel

Heading

Text in markdown.

Panel block markup:

<div class="panel panel-gitlab-orange">
**Heading**
{: .panel-heading}
<div class="panel-body">

Text in markdown.

</div>
</div>

GitLab Orange Alert Box

My text in an orange box.

Box block markup:

My text in an orange box.
{: .alert .alert-gitlab-orange}

GitLab Purple Alert Panel

Heading

Text in markdown.

Panel block markup:

<div class="panel panel-gitlab-purple">
**Heading**
{: .panel-heading}
<div class="panel-body">

Text in markdown.

</div>
</div>

GitLab Purple Alert Box

My text in an purple box.

Box block markup:

My text in an purple box.
{: .alert .alert-gitlab-purple}

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:

   The webcast I want to announce - Register here!   

{::options parse_block_html="true" /}

<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>&nbsp;&nbsp;
The webcast I want to announce - [Register here][webcast-link]!
&nbsp;&nbsp;<i class="fa fa-gitlab" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{: .alert .alert-webcast}

Styles

Yes, guess what?

This:

<style>
  .purple {
    color:inherit;
  }
  .purple:hover {
    color:rgb(107,79,187);
  }
</style>

Plus:

Hey! Hover the cursor over me and guess what?! :)
{: .purple}

Equals to:

Output

Hey! Hover the cursor over me and guess what?! :)

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


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:

<figure class="video_container">
<iframe IFRAME CONTENT></iframe>
</figure>

Google products

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

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:

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

Output:


Google Slides

Let's exemplify with this simple presentation. 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:

<figure class="video_container">
<iframe src="https://docs.google.com/presentation/d/1qDY601QTBQFIY_TOi8sP0zg7u5jgwzocysb87Upk_ho/embed?start=false&loop=false&delayms=3000" frameborder="0" width="960" height="569" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
</figure>

Output:


Google Docs

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:

<figure class="video_container">
<iframe src="https://docs.google.com/document/d/1mHhOhvvrz7xgUPyn5VWCNuKgew5MRRGZp761B9prPqs/pub?embedded=true"></iframe>
</figure>

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

<figure>
<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>
</figure>

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.

Output:


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:

{::options parse_block_html="false" /}

<div class="center">

<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

</div>

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

{::options parse_block_html="false" /}

<div class="center">

<!-- first tweet -->
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

<!-- second tweet -->
<blockquote class="twitter-tweet" data-partner="tweetdeck"><p lang="en" dir="ltr">Thanks to <a href="https://twitter.com/gitlab">@gitlab</a> for joining <a href="https://twitter.com/RailsGirlsCluj">@RailsGirlsCluj</a>! <a href="https://t.co/NOoiqDWKVY">pic.twitter.com/NOoiqDWKVY</a></p>&mdash; RailsGirlsCluj (@RailsGirlsCluj) <a href="https://twitter.com/RailsGirlsCluj/status/784847271645028352">October 8, 2016</a></blockquote>
<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>

</div>

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)

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 - screenshot of markdown doc write and preview

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


Tips & Tricks

More

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