This documentation explains Markdown syntax with practical examples, formatting rules, platform compatibility, and best practices. Use it as a complete reference while writing Markdown.
Each section includes the syntax, a working example, and notes for everyday use. Copy any example directly into your editor, README, or documentation file.
New to Markdown? Read the [beginner introduction](/blog/markdown-cheat-sheet) first, then return here when you need the full syntax reference.
The table below covers the Markdown formatting commands you'll use most often. Don't worry if you don't remember everything — the next sections explain each syntax with examples and useful tips.
| Element | Markdown Syntax |
|---|---|
| Heading | # Heading |
| Bold | **Bold Text** |
| Italic | *Italic Text* |
| Bold + Italic | ***Bold Italic*** |
| Strikethrough | ~~Text~~ |
| Link | [Title](https://example.com) |
| Image |  |
| Inline Code | `code` |
| Code Block | ```language |
| Unordered List | - Item |
| Ordered List | 1. Item |
| Task List | - [ ] Task |
| Blockquote | > Quote |
| Horizontal Rule | --- |
| Table | | Name | Age | |
Markdown is a simple way to format text using plain characters instead of toolbar buttons. You don't need special software to write it—just type a few symbols, and Markdown converts them into headings, lists, links, tables, or other formatted content.
Because the syntax is easy to learn, Markdown has become the standard format for documentation, README files, technical notes, project wikis, and knowledge bases.
Today, Markdown is supported by many popular platforms, including GitHub, GitLab, Obsidian, Notion, Discord, Stack Overflow, and countless documentation tools.
The biggest advantage is that your content stays clean and readable even before it is rendered.
Keep this page open while you write. Each section is structured for lookup, not storytelling:
Use the navigation to jump to headings, lists, tables, code blocks, or platform-specific sections (GitHub, Obsidian, Discord).
For a shorter walkthrough of the basics, see the Markdown beginner guide on the blog.
Markdown looks simple at first, but small formatting mistakes can stop your content from rendering correctly.
That's why each section below includes:
You can read the guide from start to finish or jump directly to the section you need using the navigation above.
Headings help organize your document into clear sections. Markdown supports six heading levels, from H1 to H6.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
# Markdown Cheat Sheet
## Basic Formatting
### Lists
Use only one H1 on a page. Then organize the rest of your content with H2 and H3 headings.
Wrong:
##Heading
Correct:
## Heading
Always leave one space after the # symbol.
Markdown automatically creates paragraphs when you leave a blank line between blocks of text.
This is the first paragraph.
This is the second paragraph.
Markdown keeps writing simple.
Leave one blank line to begin a new paragraph.
Keep paragraphs short. Two or three sentences are usually easier to read than one long block of text.
Sometimes you want a new line without starting a new paragraph.
Add two spaces at the end of a line or use an HTML <br> tag if your Markdown platform supports it.
First line
Second line
or
First line<br>
Second line
Use normal paragraphs whenever possible. Line breaks are best for addresses, poems, or similar content.
Use bold formatting when you want readers to notice important words.
**Bold Text**
Always **save your work** before closing the editor.
Always save your work before closing the editor.
Double asterisks (**) are the most widely supported way to create bold text.
Italic text is useful for emphasis, book titles, or subtle highlights.
*Italic Text*
Please read the *documentation* before you begin.
Please read the documentation before you begin.
Need stronger emphasis? Combine bold and italic formatting.
***Important***
***Backup your files*** before making major changes.
Backup your files before making major changes.
Strikethrough shows text that has been removed, replaced, or completed.
~~Old Text~~
~~Version 1~~
Version 2
Version 1
Version 2
Use unordered lists whenever the order of items doesn't matter.
- Item One
- Item Two
- Item Three
You can also use:
* Item
+ Item
- HTML
- CSS
- Markdown
- JavaScript
- Programming
- Python
- JavaScript
Stick with one bullet style throughout a document for consistency.
Use ordered lists when the sequence is important.
1. First
2. Second
3. Third
1. Install the software.
2. Open the editor.
3. Start writing.
Most Markdown editors automatically continue numbering as you add new items.
You can create sub-steps by indenting the next level.
1. Create a project.
1. Add a README.
2. Add documentation.
2. Commit the changes.
This is useful for tutorials, setup guides, and documentation with multiple steps.
Markdown also allows different list types together.
1. Frontend
- HTML
- CSS
- JavaScript
2. Backend
- Node.js
- Python
This works well when each numbered step contains several related items.
Small formatting habits make your documents easier to read.
These simple habits make Markdown documents look cleaner on GitHub, documentation sites, note-taking apps, and Markdown editors.
Links let readers quickly open websites, documentation, or other pages.
[Link Text](https://example.com)
[Visit MDConvertHub](https://mdconverthub.com)
You can also add a title that appears when someone hovers over the link.
[MDConvertHub](https://mdconverthub.com "Markdown Tools")
Use descriptive link text instead of phrases like "Click here." It helps readers understand where the link goes.
If your Markdown editor supports it, URLs can automatically become clickable links.
<https://mdconverthub.com>
Some platforms also detect plain URLs automatically.
https://mdconverthub.com
Create a clickable email address using Markdown.
<hello@example.com>
or
[Email Us](mailto:hello@example.com)
Images use almost the same syntax as links.
The only difference is the exclamation mark (!) at the beginning.
Always write meaningful alt text. It improves accessibility and helps explain the image if it cannot be loaded.
You can make an image clickable by wrapping it inside a link.
[](https://example.com)
Inline code highlights a command, filename, variable, or short code snippet.
`code`
Use the `npm install` command.
Use the npm install command.
Use code blocks for longer examples.
Three backticks start and end a code block.
Your code here
console.log("Hello, World!");
Many Markdown editors support language names.
```javascript
console.log("Hello");
Supported languages often include:
- JavaScript
- Python
- HTML
- CSS
- JSON
- Bash
- PHP
- Java
- C++
- TypeScript
### Quick Tip
Always specify the language when possible. It makes code much easier to read.
Markdown tables organize information into rows and columns.
| Name | Role | Experience |
|------|------|-----------|
| Alex | Developer | 5 Years |
| Emma | Designer | 3 Years |
| Name | Role | Experience |
|---|---|---|
| Alex | Developer | 5 Years |
| Emma | Designer | 3 Years |
You can align columns using colons.
| Name |
|:-----|
| Name |
|:----:|
| Name |
|-----:|
For large tables, use the Markdown Table Generator instead of creating tables manually.
Task lists are popular in GitHub projects and documentation.
- [ ] Write documentation
- [x] Publish README
Blockquotes highlight notes, quotations, or important information.
> This is a blockquote.
> Markdown focuses on readability.
Markdown focuses on readability.
> Main Quote
>> Nested Quote
Horizontal rules separate sections of a document.
Any of these work.
---
***
___
Use horizontal rules between major sections instead of adding extra blank lines.
Sometimes you want Markdown symbols to appear as normal text.
Use a backslash (\) before the character.
\*Not Italic\*
Not Italic
\*
\_
\`
\#
\[
\]
\(
\)
\\
Escaping characters is especially useful when writing tutorials or documentation about Markdown itself.
Most Markdown editors allow basic HTML.
Example:
<b>Bold Text</b>
<br>
<sup>2</sup>
<sub>2</sub>
HTML is helpful when Markdown alone cannot produce the formatting you need.
Keep HTML usage minimal so your document stays readable.
GitHub uses a version of Markdown called GitHub Flavored Markdown (GFM). It includes everything in standard Markdown, plus a few extra features that make documentation easier to write.
Some of the most useful GFM features include:
If you're writing a README file, project documentation, or issue template, GFM is the Markdown version you'll use most often.
- [x] Documentation completed
- [ ] Add screenshots
- [ ] Review examples
Obsidian stores notes as Markdown files, making them easy to edit, move, and back up.
Besides standard Markdown, Obsidian also supports features like:
Example:
[[Daily Notes]]
# Meeting Notes
- Review project
- Update documentation
If you use Obsidian every day, learning standard Markdown first makes everything else much easier.
Discord supports only a small part of Markdown.
Common formatting includes:
| Formatting | Syntax |
|---|---|
| Bold | **Text** |
| Italic | *Text* |
| Underline | __Text__ |
| Strikethrough | ~~Text~~ |
| Inline Code | code |
| Code Block | |
Not every Markdown feature works inside Discord, so tables and many advanced elements won't render.
Even experienced users make small formatting mistakes.
Wrong:
##Heading
Correct:
## Heading
Markdown is easier to read when sections are separated with blank lines.
Instead of writing everything together, leave a blank line between headings, paragraphs, and lists.
Always check that your URLs are correct.
Instead of:
[Website]()
Use:
[Website](https://example.com)
Every table row should contain the same number of columns.
Incorrect tables may not render properly on GitHub or other Markdown editors.
Instead of switching between -, *, and +, choose one style and use it consistently throughout the document.
Markdown is simple, but a few habits make your documents much easier to read.
Simple formatting is usually the easiest to maintain.
If you're using Markdown regularly, you'll probably use these elements most often:
Learning these few features is enough for most README files, documentation pages, technical guides, and personal notes.
You don't need to memorize every syntax. That's exactly why this cheat sheet exists.
Bookmark this page and come back whenever you need a quick reminder.
This page documents the Markdown syntax used in most everyday projects. Platform-specific sections and troubleshooting notes follow below.
Practice in the Markdown Editor, format tables with the Markdown Table Generator, or convert existing content with HTML to Markdown and Word to Markdown.
By this point, you've covered the Markdown syntax used in most everyday projects. The remaining sections focus on platform-specific features, practical tips, and common mistakes that help you write cleaner Markdown with fewer formatting issues.
| Task | Markdown Syntax |
|---|---|
| Link | [Text](URL) |
| Image |  |
| Inline Code | `code` |
| Code Block | ```language |
| Table | | Column | Value | |
| Task List | - [ ] Item |
| Horizontal Rule | --- |
| Escape Character | \ |
Markdown is a lightweight text formatting language that lets you create headings, lists, links, tables, code blocks, and more using simple plain text.
Yes. Markdown is an open standard and can be used without paying for software or licenses.
Markdown is commonly used on GitHub, GitLab, Obsidian, Notion, Stack Overflow, documentation websites, project wikis, and many blogging platforms.
GitHub supports GitHub Flavored Markdown (GFM), which adds extra features such as task lists, tables, and syntax highlighting while remaining compatible with standard Markdown.
Many Markdown editors allow basic HTML. However, using Markdown whenever possible keeps documents cleaner and easier to maintain.
Tables use vertical bars (|) to separate columns and dashes (---) to create the header row. For large or complex tables, using a Markdown Table Generator is usually faster than writing them manually.
Popular choices include VS Code, Obsidian, Typora, MarkText, and online Markdown editors. The best option depends on your workflow and the features you need.
Yes. Markdown can be converted into HTML, PDF, Word documents, plain text, email-friendly HTML, images, spreadsheets, and many other formats using dedicated conversion tools.