Almost every piece of text you write on GitHub, from a repository's README to an issue, a pull request description or a comment, is written in Markdown. Markdown is a simple way to format text using ordinary characters: a # at the start of a line makes a heading, **two stars** make text bold, and a line starting with - becomes a bullet point.
The beauty of Markdown is that it's readable even before it's formatted. A README.md file looks tidy in a plain text editor, and GitHub turns it into a neat web page with headings, links and highlighted code.
GitHub uses its own extended version called GitHub Flavored Markdown, which adds tables, task lists, automatic links to issues and more. In this lesson you'll learn the syntax you'll use every day and put it together into a README that makes people want to try your project.
Headings, emphasis and paragraphs
# Project title
## Installation
### Optional settings
This is **bold**, this is *italic* and this is ~~crossed out~~.- One to six
#characters make headings of decreasing size. Put a space after them. - Leave an empty line between paragraphs. A single line break inside a paragraph is ignored.
**text**is bold,*text*is italic, and~~text~~draws a line through text.- A line starting with
>becomes a quote, which is handy when replying to part of a comment.
Lists, links and images
- Item one
- Item two
- A nested item (indent by two spaces)
1. First step
2. Second step
[Codevra Git tutorial](https://www.codevra.org/git)
Links put the visible text in square brackets and the address in round brackets. Images use the same pattern with an ! in front; the text in brackets becomes the image's alt text, which screen readers announce, so describe what the picture shows. Inside a repository, use relative paths such as docs/setup.md to link to other files.
Code
Wrap short code inside a sentence in single backtick characters, the key usually found above Tab, so that npm start appears in a code font. For longer code, use a fenced code block: three backticks on the line before and after. Add a language name after the opening backticks and GitHub highlights the syntax:
```js
const total = price * quantity;
```Code blocks keep spaces and line breaks exactly as typed, which makes them the right place for commands people should copy, error messages and configuration files.
GitHub extras
| You write | You get |
|---|---|
- [ ] Write tests | A task list checkbox |
#14 | A link to issue or pull request 14 |
@samlee | A mention that notifies that person |
a1b2c3d | A link to that commit |
| A table with pipes | A formatted table |
Tables use | to separate columns and a row of dashes under the header. Task lists in an issue or pull request show progress, such as "2 of 5 tasks", wherever the issue is listed.
GitHub Markdown Syntax
Markdown quick reference
# Heading 1
## Heading 2
**bold** *italic* `code`
- bullet
1. numbered
[link text](https://example.com)
> quote
- [ ] task - [x] done task
| Col | Col |
|-----|-----|
| a | b |GitHub Markdown Summary
- Markdown formats text with plain characters, and GitHub uses it for READMEs, issues, PRs and comments.
#makes headings,**bold,*italic,-bullet lists and1.numbered lists.- Links are
[text](url); images are. - Fenced code blocks with a language name get syntax highlighting.
- GitHub adds tables, task lists, @mentions and automatic #issue links.
GitHub Markdown Examples
Each example shows the code, the output it produces and what each part does.
A clear README
# Recipe Box
A small website for saving and searching your favourite recipes.
## Features
- Search recipes by ingredient
- Save favourites in your browser
- Works on phones and tablets
## Getting started
1. Clone the repository
2. Open `index.html` in your browser
## Built with
HTML, CSS and JavaScript.Recipe Box (large heading)
A small website for saving and searching your favourite recipes.
[screenshot image]
Features (section heading)
• Search recipes by ingredient
• Save favourites in your browser
• Works on phones and tablets
Getting started
1. Clone the repository
2. Open index.html in your browser
Built with
HTML, CSS and JavaScript.Line-by-line explanation
- Line 1The project name as the only top-level heading.
- Line 3One sentence saying what the project is.
- Line 5A screenshot shows the result instantly. The alt text describes it.
- Lines 7 to 10A short feature list.
- Lines 12 to 14Numbered steps for setup.
A code block and a table
Run the tests with:
```bash
npm test
```
| Command | What it does |
|---------|--------------|
| `npm start` | Start the site |
| `npm test` | Run the tests |Run the tests with:
┌──────────────────────────┐
│ npm test │ (grey box, highlighted)
└──────────────────────────┘
Command What it does
npm start Start the site
npm test Run the testsLine-by-line explanation
- Lines 3 to 5A fenced code block labelled bash.
- Lines 7 to 10The dashes row separates the header from the data. Columns don't need to line up perfectly.
A pull request description
## What changed
Adds a search box to the header. Closes #14
## Checklist
- [x] Works on mobile
- [x] Added alt text
- [ ] Updated the README
@priya could you check the colours?What changed
Adds a search box to the header. Closes #14 (#14 becomes a link)
Checklist
☑ Works on mobile
☑ Added alt text
☐ Updated the README
@priya could you check the colours? (Priya is notified)Line-by-line explanation
- Line 2Closes #14 links the issue and closes it when the PR merges.
- Lines 5 to 7Task list items with [x] appear ticked.
- Line 9The mention sends Priya a notification.
Common GitHub Markdown Mistakes
No space after the hash
#Installation# InstallationLists without a blank line before them
Features:
- Search
- FavouritesFeatures:
- Search
- FavouritesSome Markdown viewers join the list onto the paragraph without the blank line. Adding it always works.
Images with no alt text
GitHub Markdown in Real Projects
Markdown everywhere
A project's README is its front door: it's the first thing visitors see, and a clear one with a screenshot and setup steps can make the difference between someone trying your project and closing the tab. Beyond GitHub, Markdown is used in documentation sites, note-taking apps, chat tools and many blogging platforms, so the syntax pays off far beyond this course.
GitHub Markdown FAQ
How do I add a line break without starting a new paragraph?
End the line with a backslash \ or with two spaces before pressing Enter. The backslash is easier to see when you edit the file later. You can also use the HTML tag <br>, which GitHub allows in Markdown.
How do I make a collapsible section in GitHub Markdown?
Use the HTML <details> and <summary> tags. The text inside <summary> is shown as a clickable heading, and everything else inside <details> stays hidden until someone clicks it. Leave a blank line after </summary> so the Markdown inside is formatted.
How do I show a character like * or # without formatting it?
Put a backslash in front of it: \*not italic\* shows the asterisks as written. This works for Markdown's special characters, including #, _, [ and backticks. Inside inline code or a code block, nothing is formatted, so you don't need backslashes there.
How do I add a note or warning box in a GitHub README?
Use an alert: a blockquote whose first line is > [!NOTE], followed by more > lines with the text. GitHub supports NOTE, TIP, IMPORTANT, WARNING and CAUTION, each with its own colour and icon. Other Markdown viewers show it as an ordinary quote.
Can GitHub render diagrams from Markdown?
Yes. Write a fenced code block with the language set to mermaid and Mermaid syntax inside, and GitHub draws a diagram such as a flowchart or sequence diagram. It works in README files, issues, pull requests and wikis.
GitHub Markdown Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Complete the Markdown for a second-level heading.
InstallationWhich Markdown makes text bold?
Which line is a correct Markdown link?
What does - [ ] Write tests show in a GitHub issue?
How do you get syntax highlighting for a block of Python code?
GitHub Markdown Quiz
5 questions to check what you learned.
What file name does GitHub show on a repository's front page?
- README.md
- index.html
- home.md
- about.txt
How do you make an image in Markdown?
- image
- <image path.png>
- #image path.png
- !description
What happens when you write
@samleein a comment?- Nothing
- Sam gets a notification and the name links to their profile
- Sam is added as a collaborator
- The comment is sent by email only
Why should screenshots in a README have alt text?
- It makes the image load faster
- Screen readers read it aloud, and it shows if the image fails to load
- GitHub requires it to publish
- It changes the image size
Your bullet list appears glued to the previous paragraph. What's the most likely fix?
- Add an empty line before the list
- Use * instead of -
- Put each item in quotes
- Indent the whole list by eight spaces
