Writing better README.md files using GitHub flavoured markdown

Introduction

GitHub flavoured markdown is a set of extensions to the standard markdown syntax that gives you some cool features to make your README.md files look great on GitHub. In this article, we'll look at some of the features that GitHub flavoured markdown has to offer and how you can use them in your own README.md files.

README.md Formatting

Headings

GitHub flavoured markdown supports two types of headings: setext and atx.

Setext headings are created by underlining the heading text with = for h1 headings and - for h2 headings. For example:

This is an H1
=============

This is an H2
-------------

Atx headings are created by surrounding the heading text with # characters. The number of # characters you use determines the heading level, with # being h1, ## being h2, ### being h3, and so on. For example:

# This is an H1

## This is an H2

### This is an H3

#### This is an H4

##### This is an H5

###### This is an H6

Lists

GitHub flavoured markdown supports both ordered and unordered lists.

Ordered lists are created by prefixing the list items with numbers followed by a period. For example:

1. First item
2. Second item
3. Third item

Unordered lists are created by prefixing the list items with -, +, or *. For example:
This

- First item
- Second item
+ Third item
* Fourth item

will create these:

• First item
• Second item
• Third item
• Fourth item

Images

Images are created by surrounding the image URL with ![](...). The text inside the [...] is used as the image alt text. For example:

![GitHub Logo](/images/logo.png)

Code Blocks

Code blocks are created by surrounding the code with blocks of 3 (`) . For example:


function foo() {
console.log("foo");
}


Tables

Tables are created by using the | character to create columns and the - character to create rows. For example:

These:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Row 2 | Row 3 |
| Row 4 | Row 5 | Row 6 |

will create these:

Column 1	Column 2	Column 3
Row 1	Row 2	Row 3
Row 4	Row 5	Row 6

Emoji

GitHub flavoured markdown supports emoji! 😄 To use emoji, simply type the emoji code 😄 and it will be replaced with the emoji image. For example, :smile: will be replaced with


![](https://github.githubassets.com/images/icons/emoji/unicode/1f604.png).


Conclusion

GitHub flavoured markdown is a great way to make your README.md files look great on GitHub. In this article, we've looked at some of the features that GitHub flavoured markdown has to offer and how you can use them in your own README.md files.

Resources

• GitHub Flavored Markdown Spec
• Emoji Cheat Sheet