GitHub Flavored Markdown Syntax Guide
By Chris Oung
Table of Contents
Introduction
Markdown is a lightweight and an easy-to-use syntax for styling all forms of writing on the GitHub platform. This document contains a basic overview of the markdown syntax. Use this document as a reference guide for documenting projects on the GitHub platform.
For more advanced information about the markdown syntax, see About Writing and Formatting on GitHub.
Headings
To create a heading, add one to six # symbols before your heading text. The number of # you use will determine the size of the heading.[2]
For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).
Markdown input:
# This is an h1 tag
## This is an h2 tag
### This is an h3 tag
#### This is an h4 tag
##### This is an h5 tag
###### This is an h6 tag
HTML output:
<h1>This is an h1 tag</h1>
<h2>This is an h2 tag</h2>
<h3>This is an h3 tag</h3>
<h4>This is an h4 tag</h4>
<h5>This is an h5 tag</h5>
<h6>This is an h6 tag</h6>
Emphasis
With markdown, you can add emphasis by making text bold or italic.[2]
To bold text, add two asterisks or underscores before and after a word or phrase.
Markdown input:
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
HTML output:
<em>This will be italic</em>
<em>This will also be italic</em>
<strong>This will be bold</strong>
<strong>This will also be bold</strong>
Lists
You can organize items into ordered and unordered lists.
Unordered lists
Markdown input:
* Item 1
* Item 2
* Item 2a
* Item 2b
HTML output:
<ul>
<li>Item 1</li>
<li>Item 2</li>
<ul>
<li>Item 2a</li>
<li>Item 2b</li>
</ul>
</ul>
Ordered lists
Markdown input:
1. Item 1
2. Item 2
3. Item 3
3.1. Item 3a
3.2. Item 3b
HTML output:
<ol>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
<ol>
<li>Item 3a</li>
<li>Item 3b</li>
</ol>
</ol>
Images
Markdown input:
HTML output:
<img src="/images/logo.png" alt="GitHub Logo"/>
Links
Markdown input:
[GitHub](http://github.com)
HTML output:
<a href="http://github.com">GitHub</a>
Code Blocks
To create code blocks, indent every line of the block by at least four spaces or one tab.
Markdown input:
<html>
<head>
</head>
</html>
HTML output:
<pre>
<code>
<html>
<head>
</head>
</html>
</code>
</pre>
Blockquote
To create a blockquote, add a > in front of a paragraph.
Markdown input:
> This is a blockquote.
HTML output:
<blockquote>This is a blockquote</blockquote>
[1] Source: “About Writing and Formatting on GitHub”
[2] Source: “Basic Writing and Formatting on GitHub”