Mastering Markdown for GitHub

Markdown has become an essential tool for developers to write documentation and organize projects on GitHub. With its simple syntax and automatic rendering to HTML, Markdown makes it easy to format text cleanly without needing to learn HTML.

When posting projects to GitHub, Markdown is the perfect choice for README files, issue comments, pull request messages, and any other text. GitHub applies some special extensions to "vanilla" Markdown to add helpful functionality for developers.

This guide will teach you Markdown fundamentals and GitHub specific features to help you write professional READMEs and seamless documentation.

Why Use Markdown?

Markdown was created in 2004 by John Gruber as a lightweight markup language that is readable yet can be converted cleanly to HTML. The key goals were:

• Readability – Easy to read and write in plain text without lots of symbols and coding.
• Simplicity – Syntax only handles basic formatting like headings, lists, links.
• Convertibility – Structured so it can convert seamlessly to HTML with semantic meaning.

Unlike cumbersome word processing applications, Markdown‘s sparse syntax allows writers to focus on content instead of appearance during the drafting process. Markdown documents are essentially just text files with simple formatting marks. This makes Markdown:

• Fast – No need to take hands off the keyboard to format text or insert items.
• Versatile – Works for simple notes or long-form articles and books. Plain text means less vendor lock-in.
• Portable – Markdown files work across all operating systems and devices.
• Future-proof – Since it converts to HTML, Markdown will always have a readable format.
• Collaboration-friendly – Markdown files work well with version control and edits.

Markdown became hugely popular among software developers for writing documentation. Sites like GitHub and Reddit also adopted Markdown for content creation.

The Markdown specification has remained unchanged since 2004, but many implementations have built on it with extra features like tables and syntax highlighting.

GitHub Flavored Markdown (GFM)

True to its developer roots, GitHub uses Markdown for all text input and renders it using a GitHub flavored version called GFM.

GFM builds on the original Markdown specification by adding some additional elements like:

• Task lists
• Tables
• Syntax highlighting
• Auto-linked references
• Emoji support

So regular Markdown syntax works in your GitHub docs, and you get the added functionality of GitHub‘s extensions.

Markdown By Example

Before diving further into GitHub specific features, let‘s walk through some Markdown basics with examples:

Headings

Headings help structure your document and improve scannability for readers. They are created by starting a line with the hash # symbol:

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

The number of # you use will determine the heading level, from <h1> down to <h6>.

Text Styling

For emphasizing text as italic, bold, or strikethrough, wrap words in single asterisk *, double asterisk **, or double tilde ~~:

*This displays in italics*

**This displays in bold font** 

~~This displays with a strikethrough~~

Lists

Creating bullet point lists with - or numbered lists with numbers followed by . allows you to organize information:

- First item 
- Second item
- Third item

1. First step
2. Second step 
3. Third step

Nested sub-lists can be created by indenting items with a tab or 4 spaces.

Links

Hyperlinks make it easy to link to external sites or internal documentation:

[This links to GitHub](http://github.com)

Here is the [Markdown Guide](https://www.markdownguide.org/).

GFM will automatically turn valid URLs into links so you don‘t need to explicitly create them:

http://www.example.com

Images

Upload images to your repository or link to external ones for including in your docs:

![Alternate text if no image](image.jpg)

![Hello](https://octodex.github.com/images/welcometocat.png)

Code Blocks

Code blocks display preformatted text separate from paragraphs to represent code:

```
var config = {
  apiKey:"xxx",
  authDomain: "xxxxxx",
  databaseURL: "https://xxxx.firebaseio.com",
  storageBucket: "xxxxxxxx.appspot.com"
}; 
firebase.initializeApp(config);
```

For syntax highlighting of specific languages, specify it after the “`:

```js
var config = {
  apiKey:"xxx",
  authDomain: "xxxxxx",
  databaseURL: "https://xxxx.firebaseio.com",
  storageBucket: "xxxxxxxx.appspot.com" 
};
firebase.initializeApp(config); 
```

GitHub Flavored Markdown Features

Now that you know Markdown basics, let‘s explore some special features that GitHub added:

Task Lists

Task lists allow you to include checkbox items and track progress:

- [x] Completed task
- [ ] Incomplete task 1 
- [ ] Incomplete task 2

Checking the box with x will mark it finished.

Tables

Tables help arrange data in clean rows and columns. They are created using pipes | to divide content:

| Column 1 Header | Column 2 Header | 
| ------------- | ------------- |
| Row 1 Cell 1 | Row 1 Cell 2 |
| Row 2 Cell 1 | Row 2 Cell 2 | 

Cells can be left-aligned, center-aligned, or right-aligned with colons:

| Left Align | Center Align | Right Align |
| :-- | :-: | --: |

Syntax Highlighting

Code blocks can specify a language for accurate syntax highlighting:

```ruby 
require ‘redcarpet‘
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

See the Linguist project for all supported languages.

Automatic Links

GFM will automatically create links for standard URLs, email addresses, and GitHub issue/user/repo references:

https://www.markdownguide.org/basic-syntax
fake@example.com
#1 
@octocat 
octocat/Spoon-Knife

Emoji Support :sparkles:

GitHub supports emoji! Surround the emoji code with colons to include it:

:sparkles: :camel: :boom:

Emojis add fun and emotion to conversations. Their color and animation make them stand out.

Structuring a Good README

Your project‘s README serves as the manual and first impression for others to understand why and how to use your work. GitHub recommends the following sections:

• Project name and description
• Table of contents
• Installation guide
• Usage instructions and examples
• Contributing guidelines
• Credits and references
• License statement
• Contact information

The Art of Readme guide provides outstanding advice for crafting exceptional READMEs that drive engagement. Spend time making it great since it‘s likely the first thing people read.

Helpful Markdown Tools and Extensions

Dedicated Markdown editors provide helpful productivity features like document outline views, live previews, and export options. Many code editors and IDEs also include Markdown plugins:

• VS Code – Popular free editor with live preview
• Atom – Customizable editor with Markdown addons
• MacDown – Full-featured Markdown editor for macOS
• iA Writer – Simple, elegant writing suite with Markdown support
• StackEdit – In-browser Markdown editor with rich set of features

Browser extensions can enhance your Markdown experience on GitHub and other sites:

• Markdown Here – Format email and web posts with Markdown
• Github Markdown Plugin – Instant preview on GitHub
• Markdown Reader – Reader mode optimized for Markdown files

Many static site generators like Jekyll allow creating blogs and websites authored in Markdown. This makes Markdown very popular among technical writers and bloggers.

For collaborative editing and version control, Markdown documents stored in Git repositories provide major advantages. Platforms like GitHub combine Markdown rendering with community-powered software development.

Start Writing Markdown Today

Hopefully this overview gives you the tools to start leveraging Markdown for all your project documentation and writing needs. With a little practice, you will soon memorize the common syntax elements.

The beauty of Markdown is that you can write content first without worrying too much about appearance until the end. Focus on your awesome ideas, write them down in Markdown, then format and polish prior to publishing.

Let us know if you have any other questions!