GitHub uses its own Markdown processor, which is a variant of the CommonMark specification. This means that while it supports most of the standard Markdown syntax, there are some GitHub-specific extensions and features. You can use Markdown syntax, along with some additional HTML tags, to format your writing on GitHub, in places like repository READMEs and comments on pull requests and issues.
For more examples, see the GitHub Flavored Markdown Spec.
See Writing on GitHub for more details.
Basic writing and formatting syntax
Headings
To create a heading, add one to six # symbols before your heading text. The number of # you use will determine the hierarchy level and typeface size of the heading.
This is the smallest heading
Styling text
This text is bold This text is bold and this is a link
This text is italic
This text is strikethrough
This text is bold with nested italic
This text is bold and italic
This text is subscript
This text is superscript
This text is underlined
This is a keyboard shortcut
Quoting text
This is a blockquote.
Empty Quotes
Quoting code
This is a inline code example.
print("This is a Python3 code block")
Supported color models
In issues, pull requests, and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.
The background color is #ffffff for light mode and #000000 for dark mode, also rgb(9, 105, 218).
Links
This site was built using GitHub Pages.
Section links
You can link to a section of a page by using the section's heading text, with spaces replaced by hyphens and all lowercase.
Link to the previous section: Links.
Relative links
Link to a file in the same repository: README.md.
Custom anchors
Some body text of this section.
Some text I want to provide a direct link to, but which doesn't have its own heading.
(… more content…)
Line breaks
To create a line break, end a line with two or more spaces, and then type return.
Line one.
Line two.
or use the HTML <br> tag.
Line one.
Line two.
Images
Hosted images
Lists
You can make an unordered list by preceding one or more lines of text with -, *, or +.
- George Washington
- John Adams
- Thomas Jefferson
To order your list, precede each line with a number.
- James Madison
- James Monroe
- John Quincy Adams
Nested Lists
- First list item
- First nested list item
- Second nested list item
- First nested list item
Ignoring Markdown formatting
You can tell GitHub to ignore (or escape) Markdown formatting by using \ before the Markdown character.
Let's rename *our-new-project* to *our-old-project*.
Adding an image to suit your visitors
Example of a responsive image
Adding a table
Hi, I'm Mona. You might recognize me as GitHub's mascot.
| Rank | Languages |
|---|---|
| 1 | JavaScript |
| 2 | Python |
| 3 | SQL |
Adding a collapsed section
My top languages
| Rank | Languages |
|---|---|
| 1 | JavaScript |
| 2 | Python |
| 3 | SQL |
Adding a divider
Adding a video
We can't use an <iframe> tag to embed a video, but we can link to a video on YouTube or another site and display a thumbnail image that links to the video.
Adding a quote
Example of a quote
If we pull together and commit ourselves, then we can push through anything.
— Mona the Octocat
Work with advanced formatting
Creating a table
| Left-aligned | Center-aligned | Right-aligned |
|---|---|---|
| git status | git status | git status |
| git diff | git diff | git diff |
| Pipe | | |
| Command | Description |
|---|---|
git status | List all new or modified files |
git diff | Show file differences that haven't been staged |
Creating a collapsed section
Tips for collapsed sections
You can add a header
You can add text within a collapsed section.
You can add an image or a code block, too.
puts "Hello World"
iframe tag
The <iframe> tag is not supported in GitHub Markdown. You can link to an external site instead.