Markdown is a lightweight markup language with simple syntax for creating formatted text. Put more simply, Markdown makes it easy to create formatted text for a variety of uses not including GitHub, such as blogging. certain messaging platforms, documentation, and specific to what you're interested in today, README files.
GitHub uses its own version of Markdown, referred to as GitHub Flavored Markdown. It also supports rendering Markdown (.md) files, which is to say, if you add a Markdown file to a GitHub repository, it will show up formatted when you click on it on GitHub. Adding a README.md file to a normal GitHub repository will render it below the list of files contained within the repo. Adding a README to your special new repository will render it on your main account page on GitHub!
However, before you can get started with making your new profile, you're going to need to have a basic understanding of Markdown. This page will cover some basics, and include a link to a separate guide that goes into more detail.
Markdown Syntax
Creating headings, and bold, italic, and strikethrough formatted text (as well as various combinations thereof) are simple to do with Markdown.
Markdown Headings
Headings are formatted using various numbers of # in front of the heading text. One # indicates the largest heading, two # indicate the second largest heading, and six # indicate the smallest possible heading.
The following is an example of Markdown headings.
# Sample Heading Text ## Sample Heading Text ###### Sample Heading Text
The above Markdown renders as shown below.
Markdown Text Formatting
Text formatting with Markdown is relatively simple, once you get the hang of it. A few basic formatting options are included below.
- The first column is the specific formatting style.
- The second column is the Markdown formatting. The formatting options shown once are expected to be on both sides of the text you wish to format. See third column for examples.
- The third column is an example using the Markdown.
- The fourth column is the Markdown example rendered.
| Style | Markdown | Example | Rendered |
|---|---|---|---|
| Bold |
** or __
|
**Bold text** or __Bold Text__
|
Bold text or Bold text |
| Italics |
* or _
|
*Italics text* or _Italics text_
|
Italics text or Italics text. |
| Strikethrough | ~~ |
~~Strikethrough text~~ |
|
| Bold and nested italics |
** and _
|
**Bold and nested _italics_ text** |
Bold and nested italics text |
| Entirely bold and italics | *** |
***Entirely bold and italics text*** |
Entirely bold and italics text |
Markdown Image Embedding
Markdown allows you to easily embed images that you have uploaded to GitHub. Add an exclamation point, !, to the start of the line, immediately followed by the alt text wrapped in brackets, [], immediately followed by the image link wrapped in parentheses, ().
Here is an example image embed line.
This line would render the following image:
Check out the Add an Image page in this guide for details on how to upload an image to GitHub.
Markdown Code Formatting
Markdown makes it simple to include formatted code snippets.
To format code inline or line-by-line, include ` (a single backtick) on either side of the code to render it as code. For example, `Hello, World!` would render as Hello, World!.
To format a codeblock, include ``` (three backticks) on either end of the codeblock. For example:
```
print("Hello, World!")
while True:
print("This is a loop!")
```
Would render as:
print("Hello, World!")
while True:
print("This is a loop!")
Markdown List Formatting
Making lists with Markdown is pretty intuitive. For a bullet list, use either * or - at the beginning of each line in the list.
For example, the following:
* Bullet line one * Bullet line two or - Bullet line one - Bullet line two
Would render as:
- Bullet line one
- Bullet line two
or
- Bullet line one
- Bullet line two
For numbered lists, you would use a number followed by a period, such as 1., at the beginning of each line.
For example:
1. Numbered line one 2. Numbered line two
Would render as:
- Numbered line one
- Numbered line two
A Nifty Collapsing Trick
You may find that your Markdown file is getting a bit long. Perhaps some of the information is important to you to include, but might be secondary to other more crucial information. Wouldn't it be convenient to display a by-default collapsed section that folks can click on if they are interested in more information? Here's a nifty trick to do exactly that.
To create a collapsed section your Markdown file, include the following code.
### A collapsible section with Markdown <details> <summary>Click here for more information!</summary> More information here. </details>
Two important notes:
- You must leave an empty line below the closing
</summary>tag, otherwise the Markdown will not render properly. - Leave an empty line below the closing
</details>tag if you have multiple collapsing blocks.
GitHub Flavored Markdown Resources
For a more in-depth look at GitHub Flavored Markdown basics, check out this excellent Basic writing and formatting syntax guide. It covers everything covered here including more detail, and a number of formatting options not covered here.
If you're interested in some more advanced formatting, check out the next section in the same guide, Working with advanced formatting.
