Common Markdown Syntax

This document gathers all the Markdown syntax that are supported by both GitHub and GitLab. This is very useful for creating documentation for those platforms simultaneously.

Only the Markdown syntax that are common between the documentations below are highlighted here.

• GitHub
  • GitHub Docs - Basic Writing and Formatting Syntax.
  • GitHub Docs - Working with Advanced Formatting.
  • GitHub Flavored Markdown Spec.
• GitLab
  • GitLab Flavored Markdown.
  • GitLab Syntax Rendered.

This is meant for personal use to ease writing documentation on both GitHub and GitLab for the same project/repository.

I might add other platforms here, but I don't plan to seriously maintain any of this. However, feel free to fork and create your documentation from this.

---

Headings

Syntax

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Output

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

---

Line Breaks

Paragraphs

Syntax

This is the first paragraph.
This will not be counted as a new line.

However, an empty line will create a paragraph. So, this is the second paragraph.

Output
This is the first paragraph. This will not be counted as a new line.

However, an empty line will create a paragraph. So, this is the second paragraph.

New Line

Sytnax

This is line 1.
But this won't be next line.\
This, however, is the line 2, because of the backslash (`\`) in previous line.  
And this is also in next line, because of double-space (`  `).

Output
This is line 1. But this won't be next line.
This, however, is the line 2, because of the backslash (\) in previous line.
And this is also in next line, because of double-space ( ).

---

Emphasis / Styling

Style	Syntax	Example	Output
Bold	** ** or __ __	**This is bold text**	This is bold text
Italic	* * or _ _	_This text is italicized_	This text is italicized
Strikethrough	~~ ~~ or ~ ~	~~This was mistaken text~~	This was mistaken text
Bold and nested italic	** ** and _ _	**This text is _extremely_ important**	This text is extremely important
All bold and italic	*** ***	***All this text is important***	All this text is important
Subscript	<sub> </sub>	This is a <sub>subscript</sub> text	This is a subscript text
Superscript	<sup> </sup>	This is a <sup>superscript</sup> text	This is a superscript text
Underline	<ins> </ins>	This is an <ins>underlined</ins> text	This is an underlined text

---

Horizontal Line

Note

• GitHub automatically adds a horizontal line when rendering headings, but it doesn't modify the text.
• Horizontal lines turn the respective lines above into a Heading. See the renderings in Output section below.

Syntax

Option 1: using Hyphens (-)
---

Option 2: using Asterisks (*)
***

Option 3: using Underscores (_)
___

Output

Option 1: using Hyphens (-)

Option 2: using Asterisks (*)

---

Option 3: using Underscores (_)

---

---

Lists

Unordered Lists

Syntax

- Option 1: using Hyphen / Minus (-)
  - Sub-item with indentation.
    - Nesting with more indentation.
+ Option 2: using Plus (+)
  + Sub-item with indentation.
    + More indentation.
* Option 3: using Asterisk (*)
  * Sub-item with indentation.
    * More indentation.

Output

• Option 1: using Hyphen / Minus (-)
  • Sub-item with indentation.
    • Nesting with more indentation.

• Option 2: using Plus (+)
  • Sub-item with indentation.
    • More indentation.

• Option 3: using Asterisk (*)
  • Sub-item with indentation.
    • More indentation.

Ordered Lists

Syntax

1. Type "1." and a Space to create first item.
2. Continue the numbering to add more items.
   1. Indent to create sub-item.
      1. Nesting is also supported.

Output

1. Type "1." and a Space to create first item.
2. Continue the numbering to add more items.
   1. Indent to create sub-item.
      1. Nesting is also supported.

Mixing List Types

Syntax

1. Unordered List
   - Item 1
     1. Ordered sub-list.
     2. Continuing the order.

- Ordered List
  1. Starting here.
  2. Continuing.
     - No order in sub-items.
     - No order here too!

Output

1. Unordered List
   • Item 1
     1. Ordered sub-list.
     2. Continuing the order.

• Ordered List
  1. Starting here.
  2. Continuing.
     • No order in sub-items.
     • No order here too!

---

Task Lists

Syntax

- [ ] Unchecked item.
- [x] Checked item.
  - [ ] Sub-tasks with indentation.

Output

• Unchecked item.
• Checked item.
  • Sub-tasks with indentation.

---

Links

Syntax

- Inline-style link: [Example Domain](https://example.com/)
- File in _same directory_: [Example Text File](example.txt)
- Relative link: [File inside a sub-directory](ExampleDirectory/Example2.txt)
- Link to a Section: [This goes to the top Heading](#common-markdown-syntax)
- Link to Section in another Markdown file: [Example.md Link](example.md#example-heading-1)
- URL Auto-linking:
  - https://www.google.com
  - ftp://ftp.us.debian.org/debian/
  - smb://foo/bar/baz
  - irc://irc.freenode.net/
  - http://localhost:3000

Output

• Inline-style link: Example Domain
• File in same directory: Example Text File
• Relative link: File inside a sub-directory
• Link to a Section: This goes to the top Heading
• Link to Section in another Markdown file: Example.md Link
• URL Auto-linking (some might not work in GitHub):
  • https://www.google.com
  • ftp://ftp.us.debian.org/debian/
  • smb://foo/bar/baz
  • irc://irc.freenode.net/
  • http://localhost:3000

---

Quote Blocks

Syntax

> This is a Block Quote.  
> This is another line in the Block Quote.  
> This is how the "Syntax" and "Output" sections are written here.  
> > They can also be nested like this.

Output

This is a Block Quote.
This is another line in the Block Quote.
This is how the "Syntax" and "Output" sections are written here.

They can also be nested like this.

---

Alert Blocks

Syntax

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]  
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]  
> Negative potential consequences of an action.

Output

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Note

Nesting and Indentation

GitLab Flavored Markdown supports nesting and indentation alignment of the Alert Blocks, but GitHub Flavored Markdown doesn't support it.

The block below will be rendered as intended in GitLab, but not in GitHub.

Syntax

- This is a Note block
	> [!NOTE]
	> Highlights information that users should take into account, even when skimming.
- This is a Tip block
	> [!TIP]
	> Optional information to help a user be more successful.
- This is an Important block
	> [!IMPORTANT]
	> Crucial information necessary for users to succeed.
- This is a Warning block
	> [!WARNING]
	> Critical content demanding immediate user attention due to potential risks.
- This is a Caution block
	> [!CAUTION]
	> Negative potential consequences of an action.

Output

• This is a Note block

  [!NOTE] Highlights information that users should take into account, even when skimming.

• This is a Tip block

  [!TIP] Optional information to help a user be more successful.

• This is an Important block

  [!IMPORTANT] Crucial information necessary for users to succeed.

• This is a Warning block

  [!WARNING] Critical content demanding immediate user attention due to potential risks.

• This is a Caution block

  [!CAUTION] Negative potential consequences of an action.

---

Code Blocks

Basic code block

Syntax

```
checkEvenOdd(number){
	if number is divisble by 2,
		return "Even"
	else, return "Odd"
}
```

Output

checkEvenOdd(number){
	if number is divisble by 2,
		return "Even"
	else, return "Odd"
}

Syntax Highlighting

Note

• GitHub's supported languages and keywords ("name" and "aliases" fields in the YAML file). GitHub uses Linguist.
• GitLab's supported languages and keywords. GitLab uses Rogue Ruby library.

Syntax
Written in Bash

```bash
checkEvenOdd() {
	local number=$1
	
	if (( number % 2 == 0 )); then
		printf "Even"
	else
		printf "Odd"
	fi
}
```

Written in Markdown

```md
# This is a Markdown Syntax
1. All Markdown syntax are _highlighted_ here.
- But, they're **not rendered**
```

Written in XML

```xml
<?xml version="1.0" encoding="UTF-8"?>
<library>
    <book id="b1">
        <title>The Adventures of Sherlock Holmes</title>
        <author>Arthur Conan Doyle</author>
        <year>1892</year>
    </book>

    <book id="b2">
        <title>Pride and Prejudice</title>
        <author>Jane Austen</author>
        <year>1813</year>
    </book>
</library>
```

Output
Written in Bash

checkEvenOdd() {
	local number=$1
	
	if (( number % 2 == 0 )); then
		printf "Even"
	else
		printf "Odd"
	fi
}

Written in Markdown

# This is a Markdown Syntax
1. All Markdown syntax are _highlighted_ here.
- But, they're **not rendered**

Written in XML

<?xml version="1.0" encoding="UTF-8"?>
<library>
    <book id="b1">
        <title>The Adventures of Sherlock Holmes</title>
        <author>Arthur Conan Doyle</author>
        <year>1892</year>
    </book>

    <book id="b2">
        <title>Pride and Prejudice</title>
        <author>Jane Austen</author>
        <year>1813</year>
    </book>
</library>