Markdown Syntax, Explained
A Markdown cheat sheet and guide: headings, lists, links, images, code, tables and task lists, plus the line-break and escaping rules that trip people up.
By Udit Agarwal · Updated October 18, 2026
Markdown is a plain-text formatting syntax: you mark up ordinary text with a few symbols, such as # for a heading, asterisks for emphasis and a hyphen for a list item, and a program turns it into HTML. John Gruber created it in 2004 so that a document would still read naturally as plain text. It is the format of README files, much of the documentation on the web, and the message box of many forums and chat apps.
| You type | You get |
|---|---|
# Heading 1 to ###### Heading 6 |
Headings, from level 1 to level 6 |
**bold** or __bold__ |
bold |
*italic* or _italic_ |
italic |
~~struck~~ |
|
`code` |
code |
[link text](docs/setup.md) |
A link |
 |
An image |
- item or * item |
A bulleted list |
1. item |
A numbered list |
- [ ] to do and - [x] done |
A task list (GitHub Flavored Markdown) |
> quoted text |
A blockquote |
--- on its own line |
A horizontal rule |
```js above the code and ``` below |
A fenced code block |
\* |
A literal asterisk |
Two spaces or \ at the end of a line |
A line break |
You will find Markdown in README.md files on GitHub and GitLab, in documentation sites and static-site generators, in the text cells of Jupyter notebooks, in note-taking apps, and on forums such as Reddit and Stack Overflow. Chat apps such as Discord and Slack accept a subset with rules of their own; in Slack, for example, single asterisks make text bold.
Gruber's original description left many cases open, so early renderers disagreed. CommonMark, first published in 2014, pinned the rules down in a precise specification. GitHub Flavored Markdown (GFM) is a superset of CommonMark that adds tables, task lists, strikethrough and automatic links for bare URLs. When the same text looks different in two places, the flavor is usually why. The GFM specification is the reference for everything in this guide that goes beyond the basics.
A heading is one to six hash signs, then a space, then the text: ## Installation is a level-2 heading. The space matters, and #Installation stays plain text in CommonMark. Paragraphs are separated by a blank line.
Wrap text in one asterisk or underscore on each side for italic, two for bold and three for both. There is one asymmetry worth knowing: underscores inside a word are ignored, so snake_case_name comes out as written, but asterisks inside a word still count, so 2*3*4 turns the 3 italic.
For a bulleted list, start each line with -, * or + and a space. Changing the symbol partway through starts a new list. For a numbered list, use a number followed by a period. Only the first number counts: three lines that all begin 1. render as 1, 2, 3, and a list that begins at 3. starts counting from 3. To nest a list, indent the child item to line up with the parent's text, which is two spaces under - and three under 1. .
A link puts the visible text in square brackets and the address in parentheses, with an optional title in quotes: [Setup guide](docs/setup.md "How to install"). Wrapping a URL in angle brackets, as in <https://example.com>, links it as is, and GitHub Flavored Markdown also links bare https:// and www. addresses on its own. For long documents, reference-style links keep paragraphs tidy: write [Setup guide][setup] in the text and put [setup]: docs/setup.md on its own line anywhere in the file.
An address with a space in it breaks the link, because the space ends the URL. Encode the space as %20 ([Report](my%20report.pdf)) or wrap the address in angle brackets ([Report](<my report.pdf>)). The URL encoding guide explains which other characters need the same treatment.
An image is a link with an exclamation mark in front: . The text in brackets becomes the alt text, which screen readers announce and browsers show if the image fails to load, so describe the picture rather than writing "image".
Inline code goes between backticks: `npm install`. To show a backtick inside inline code, wrap it in double backticks. For a block of code, put a line of three backticks above and below it, and name the language after the opening fence so that renderers which support highlighting, such as GitHub, can color it:
```js
console.log("Hello, world");
```
Three tildes work in place of backticks. Markdown also treats any line indented by four spaces as code, the original way of writing a code block, which is why a paragraph indented that far suddenly turns monospaced.
A line starting with > becomes a blockquote, and > > nests one quote inside another. Three hyphens, asterisks or underscores on a line by themselves draw a horizontal rule. Leave a blank line above ---, though: placed directly under a line of text, it turns that line into a heading instead.
Tables and task lists are GitHub Flavored Markdown features, not part of original Markdown. A table needs a header row, then a delimiter row of dashes, then the data, with pipes between cells. Colons in the delimiter row set the alignment: :--- for left, :---: for center and ---: for right.
| Fruit | Stock | Price |
| :----- | :---: | ----: |
| Apple | 50 | 1.20 |
| Cherry | 0 | 4.00 |
The pipes do not have to line up; the padding above is only for people reading the source. A cell holds inline formatting only, so lists and code blocks cannot go inside a table, and a literal pipe in a cell must be escaped as \|. Typing tables by hand gets tedious quickly. The Markdown Table Generator builds one in an editable grid, and CSV to Markdown Table converts a spreadsheet export in one paste.
A task list is a bulleted list whose items begin with [ ] for an open item or [x] for a finished one:
- [x] Write the README
- [ ] Add screenshots
Line breaks. A single newline inside a paragraph is a soft break, and CommonMark renders it as a space. Two lines typed one under the other therefore come out as one line. To force a break, end the line with two spaces, end it with a backslash, or use an HTML <br> tag. Two trailing spaces are invisible, and editors that trim trailing whitespace delete them on save, so the backslash is the safer habit. A blank line starts a new paragraph.
GitHub adds a twist. In issues, pull requests and discussions it shows every newline as a line break, but in .md files such as a README it follows the standard rule. The same text can therefore look right in a comment and run together in a README.
Escaping. A backslash before a punctuation character makes Markdown show the character instead of acting on it: \*not italic\*, \# or \_. The classic trap is a sentence that starts with a year: "1986. A great year." becomes a numbered list that starts at 1986, and writing 1986\. fixes it. Text in angle brackets can also vanish, because Markdown passes HTML through and the browser treats <placeholder> as an unknown tag. Inside code spans and code blocks nothing needs escaping, since everything there is shown exactly as typed.
The Markdown Preview renders GitHub Flavored Markdown next to the editor as you type, with tables, task lists as checkboxes, strikethrough, fenced code blocks and automatic links. By default a single newline becomes a line break, as in a comment. Switch on GitHub style and newlines follow the README rule instead, with GitHub-like styling. Each heading in the preview has a Copy button for that section's Markdown, the editor shows word and character counts with a reading time, and the result can be copied as HTML or as plain text, downloaded as an .html file, or saved as a PDF through your browser's print dialog.
Script, style and iframe tags, inline event handlers and javascript: links are stripped from the preview and from the HTML you copy; other inline HTML, such as <kbd>, is kept. Code blocks are shown in a monospaced font without syntax coloring, and footnotes are not rendered. Your text is converted in your browser and is not uploaded, though images you reference by URL load from wherever they are hosted. To go the other way, HTML to Markdown converts a web page or snippet, and Markdown to PDF lays out a .md file as a paginated document.
What is Markdown used for? Writing formatted text in plain text files. It is the standard format for README files and project documentation, and many forums, note apps and chat tools accept it for messages and notes. A renderer converts it to HTML for display.
How do I make a new line in Markdown? End the line with two spaces or a backslash, or insert an HTML br tag. A single newline on its own is shown as a space in standard Markdown and in GitHub README files. A blank line starts a new paragraph instead.
How do I make a table in Markdown? Write a header row with pipes between the cells, then a row of dashes, then one row per line of data. Colons in the dashed row set left, center or right alignment. Tables are part of GitHub Flavored Markdown, so check that your platform supports that flavor.
What is the difference between Markdown and GitHub Flavored Markdown? GitHub Flavored Markdown is an extended version of standard Markdown. It follows the precise CommonMark rules and adds tables, task lists, strikethrough and automatic links for plain URLs, which original Markdown does not have.
How do I add a code block with syntax highlighting? Put three backticks on the line above the code and three on the line below, and write the language name right after the first three, for example js or python. Platforms that support highlighting, such as GitHub, then color the code by language.
Can you change the text color in Markdown? Markdown has no syntax for color. Some renderers allow inline HTML such as a span with a style attribute, but GitHub removes style attributes, so colored text does not survive in a README. If you are picking colors for a page or a theme instead, the guide to HEX, RGB and HSL color codes explains the notations.
How do I type an asterisk without making italics? Put a backslash in front of it, so a backslash and an asterisk show a single asterisk. The same works for underscores, hash signs, backticks and other punctuation. Inside inline code, characters are shown literally and need no backslash.
All Code Formatters tools · All guides