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.

Sample Heading Text

Sample Heading Text

Sample Heading Text

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~~ 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.

![The Adafruit Discord Badge](https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg)

This line would render the following image:

The Adafruit Discord Badge

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:

  1. Numbered line one
  2. 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:

  1. You must leave an empty line below the closing </summary> tag, otherwise the Markdown will not render properly.
  2. 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.

This guide was first published on Jul 06, 2022. It was last updated on Mar 08, 2024.

This page (Markdown Basics) was last updated on Mar 08, 2024.

Text editor powered by tinymce.