---
title: "Markdown"
description: "Markdown is a lightweight markup language designed for creating formatted text using a simple, readable syntax. It's widely used for documentation, READMEs, blogs, and content creation across the web."
author: "Mohammad Abu Mattar"
canonical: https://mkabumattar.com/cheatsheets/markdown
---
# Markdown
Markdown is a lightweight markup language designed for creating formatted content with a simple, readable syntax. Originally created for web writing, it's now used everywhere from documentation to blogs to note-taking apps.
Browse the sections below to explore Markdown syntax, formatting options, and practical examples.
## Getting Started
Fundamental Markdown concepts and basic syntax for beginners.
### Basic Syntax
Introduction to Markdown file format and basic structure.
**Keywords:** markdown, syntax, plain text, markup, file format
#### Simple Markdown file
```markdown
# My First Markdown File
This is a paragraph of plain text that will be rendered as normal text.
You can use **bold** and *italic* text easily.
```
Demonstrates a basic Markdown file with headings, paragraphs, and inline formatting.
- Markdown files typically use .md or .mdx extensions.
- Plain text is rendered as-is, with newlines creating paragraphs.
#### Markdown file with structure
```markdown
# Main Title
## Chapter One
### Section 1.1
This section introduces the topic.
Key points:
- First point
- Second point
```
Shows hierarchical document structure using different heading levels.
- Use consistent heading levels for better document organization.
- Markdown is ideal for documentation and content-first writing.
**Best practices:**
- Keep your Markdown simple and readable in plain text form.
- Use consistent formatting throughout your document.
- Choose .md or .mdx extension based on your needs.
**Common errors:**
- **Inconsistent heading levels creating confusing hierarchy.**: Use heading levels sequentially (H1, then H2, not H1 then H3).
### Headers
Create document headers and section titles using H1 through H6.
**Keywords:** headers, headings, h1, h2, h3, h4, h5, h6
#### Hash-style headers
```markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
```
Hash symbols create heading levels from H1 to H6.
- More hashes = smaller heading.
- Space after hash is required in most Markdown parsers.
#### Underline-style headers
```markdown
Heading 1
=========
Heading 2
---------
```
Underlines with equals or dashes create H1 and H2 headers.
- Underline method only supports H1 and H2.
- Less commonly used than hash syntax.
#### Headers with special characters
```markdown
# Getting Started with APIs
## Installation & Configuration
### FAQ: Common Questions
```
Headers can include special characters like &, ?, and numbers.
- Special characters are preserved in headers.
- Headers are often converted to URL-friendly slugs for links.
**Best practices:**
- Use H1 once per document as the main title.
- Use sequential heading levels to maintain document structure.
- Keep headers concise and descriptive.
**Common errors:**
- **Multiple H1 headers in one document.**: Use only one H1 as the document title, rest as H2+.
- **No space after hash symbol.**: Use '# Heading' not '#Heading'.
### Emphasis and Formatting
Apply bold, italic, strikethrough, and inline code formatting.
**Keywords:** bold, italic, strikethrough, emphasis, formatting, inline code
#### Bold and italic text
```markdown
This is **bold text**.
This is *italic text*.
This is ***bold and italic text***.
This is __underscored bold__.
This is _underscored italic_.
```
Different ways to apply bold and italic emphasis to text.
- Asterisks (*) and underscores (_) both work for emphasis.
- **bold** and __bold__ are equivalent.
#### Strikethrough and inline code
```markdown
This is ~~strikethrough text~~.
Use `inline code` for functions and variables.
The `console.log()` function outputs to the terminal.
```
Strikethrough and backticks for inline code formatting.
- Strikethrough uses double tildes (~~).
- Backticks (``) preserve text formatting exactly.
#### Combined emphasis
```markdown
**Bold text with `code` inside**
***Italic and bold with `code`***
**This is ~~important~~ no longer important**
```
Combining multiple emphasis styles in the same text.
- Nesting emphasis works well for describing code and features.
- Keep combined emphasis readable and meaningful.
**Best practices:**
- Use bold for important terms and concepts.
- Use italic for emphasis and titles.
- Use backticks for code references.
**Common errors:**
- **Using emphasis for purely visual effect.**: Use emphasis semantically to highlight important information.
## Lists and Nesting
Create ordered and unordered lists with proper nesting and indentation.
### Unordered Lists
Create bullet-point lists using -, *, or + symbols.
**Keywords:** unordered lists, bullets, dash, asterisk, plus, nested lists
#### Simple unordered list
```markdown
- First item
- Second item
- Third item
* Alternative bullet style
* Another item
+ Yet another style
```
Basic unordered lists with three different bullet styles.
- All three symbols (-, *, +) are equivalent.
- Consistency within a document is recommended.
#### Nested unordered list
```markdown
- Parent item 1
- Child item 1.1
- Child item 1.2
- Grandchild item 1.2.1
- Parent item 2
- Child item 2.1
```
Multi-level nested list demonstrating indentation structure.
- Indent with 2-4 spaces for each nesting level.
- Most parsers accept 2-space indentation.
#### List with multiple items
```markdown
- JavaScript
- Frameworks: React, Vue, Angular
- Libraries: D3, Three.js
- Python
- Frameworks: Django, Flask
- Libraries: NumPy, Pandas
```
Categorized nested list structure with multiple levels.
- Well-structured lists are easier to read and understand.
**Best practices:**
- Use consistent bullet symbols throughout.
- Indent nested items by 2-4 spaces.
- Keep list items concise.
**Common errors:**
- **Insufficient indentation for nested items.**: Use at least 2 spaces for each nesting level.
### Ordered Lists
Create numbered lists with 1., 2., 3. syntax.
**Keywords:** ordered lists, numbered lists, enumeration, sequence, nested numbered
#### Simple numbered list
```markdown
1. First step
2. Second step
3. Third step
4. Fourth step
```
Basic ordered list with numeric sequence.
- Numbers don't need to be sequential in source (1, 1, 1 renders as 1, 2, 3).
- Using correct numbers helps readability in the source.
#### Nested numbered and mixed lists
```markdown
1. Installation
1. Download the package
2. Extract the archive
3. Run setup
2. Configuration
- Set environment variables
- Update config file
- Verify settings
3. Verification
1. Run tests
2. Check output
```
Nested ordered list with mixed bullet points and numbers.
- Mix ordered and unordered lists at different nesting levels.
- Indentation determines the nesting relationship.
#### Ordered list with code and formatted text
```markdown
1. **Install** the package: `npm install markdown-parser`
2. **Import** in your file: `const md = require('markdown-parser')`
3. **Parse** your content with `md.parse(content)`
```
Numbered list items with inline code and bold formatting.
- Lists items can contain inline formatting.
**Best practices:**
- Use ordered lists for steps or sequences.
- Use unordered lists for non-sequential items.
- Keep numbered items at similar detail levels.
**Common errors:**
- **Incorrect indentation for sub-lists.**: Indent nested lists consistently (2-4 spaces).
### Task Lists
Create checkbox lists with [ ] and [x] for task tracking.
**Keywords:** task lists, checkboxes, tasks, todo, completed, unchecked
#### Simple task list
```markdown
- [ ] Learn Markdown basics
- [ ] Create first document
- [x] Review formatting options
```
Task list with unchecked and checked items.
- Space between brackets is required: `[ ]` not `[]`.
- Checked items use lowercase 'x': `[x]`.
#### Nested task list with sub-tasks
```markdown
- [ ] Project setup
- [x] Create repository
- [ ] Initialize package.json
- [ ] Install dependencies
- [ ] Development
- [ ] Write functions
- [ ] Write tests
- [x] Documentation complete
```
Hierarchical task list with parent and sub-tasks.
- Task lists are supported by GitHub, GitLab, and many Markdown renderers.
- They're useful for project planning and issue tracking.
#### Task list with descriptions
```markdown
- [x] **Setup** - Install all required packages
- [ ] **Development** - Write core functionality
- [ ] `auth.js` - User authentication
- [ ] `database.js` - Database operations
- [ ] **Testing** - Write and run test suite
- [ ] **Documentation** - Update README files
```
Task list with formatted descriptions and inline code.
- Combine task lists with formatting for clarity.
**Best practices:**
- Use task lists for progress tracking.
- Keep task descriptions clear and specific.
- Update checkbox status as work progresses.
**Common errors:**
- **Using [X] instead of [x] for completed items.**: Use lowercase 'x' for checked items.
## Links and Images
Create hyperlinks and embed images using inline and reference syntax.
### Inline Links
Create links using [text](url) syntax with optional titles.
**Keywords:** links, hyperlinks, urls, inline links, anchor, href
#### Basic inline links
```markdown
[Visit OpenAI](https://openai.com)
[GitHub Profile](https://github.com)
[Documentation](https://example.com/docs)
```
Simple inline links with descriptive anchor text.
- Link text must be descriptive, not "click here".
- URLs must include protocol (http:// or https://).
#### Links with title attribute
```markdown
[Visit OpenAI](https://openai.com "OpenAI Official Site")
[Python Docs](https://docs.python.org "Python Documentation")
```
Links with title attributes that display on hover.
- Title is optional and uses double quotes.
- Titles improve user experience with context.
#### Links within text
```markdown
For more information, check the [official documentation](https://docs.example.com).
Learn [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) from authoritative sources.
```
Inline links embedded within paragraph text.
- Links can be placed mid-sentence naturally.
**Best practices:**
- Use descriptive link text that indicates destination.
- Verify links are correct before publishing.
- Use secure HTTPS URLs when possible.
**Common errors:**
- **Using "click here" as link text.**: Use descriptive text like "Read the documentation".
### Reference Links
Create reusable links using [text][ref] and [ref]: url syntax.
**Keywords:** reference links, link references, reusable links, definitions
#### Basic reference-style links
```markdown
This is [a link][ref1] and [another link][ref2].
[ref1]: https://example.com
[ref2]: https://example.org
```
Reference-style links defined separately from content.
- Reference definitions can appear anywhere in the document.
- Usually placed at the end for better readability.
#### Reference links with multiple definitions
```markdown
[Visit][home] our site or check [documentation][docs].
Learn about [pricing][pricing].
[home]: https://example.com
[docs]: https://docs.example.com
[pricing]: https://example.com/pricing
```
Multiple reference links with clear definitions.
- Reference links reduce duplication in long documents.
#### Implicit reference links
```markdown
Visit [GitHub] for version control.
Check [Stack Overflow] for answers.
[GitHub]: https://github.com
[Stack Overflow]: https://stackoverflow.com
```
Reference links where text and reference are identical.
- Implicit references simplify the syntax.
**Best practices:**
- Use reference links for frequently used URLs.
- Group reference definitions at the end.
- Use lowercase reference names for consistency.
**Common errors:**
- **Reference definitions not matching link references.**: Ensure reference names match exactly (case-sensitive).
### Images
Embed images using  syntax with optional titles.
**Keywords:** images, img, picture, alt text, accessibility
#### Basic image syntax
```markdown
```
Inline images with alt text and paths.
- Alt text is required for accessibility.
- URLs can be absolute or relative.
#### Images with title attribute
```markdown
```
Images with title attributes for additional context.
- Titles display on hover in web browsers.
#### Reference-style images
```markdown
![Markdown][logo]
![Another Image][img2]
[logo]: https://markdown-guide.readthedocs.io/_images/markdown-mark.svg "Markdown Logo"
[img2]: ./images/banner.png
```
Reference-style image embedding with definitions.
- Reference images work like reference links.
**Best practices:**
- Use descriptive alt text for all images.
- Optimize images for web use.
- Use relative paths for local images when possible.
**Common errors:**
- **Empty or missing alt text.**: Always provide meaningful alt text describing the image.
## Code and Quotes
Format code blocks and blockquotes for documentation and references.
### Inline Code
Wrap code references in backticks for inline formatting.
**Keywords:** inline code, backticks, code formatting, keywords, monospace
#### Basic inline code
```markdown
Use the `console.log()` function to print output.
The `Array.map()` method transforms arrays.
Call `myFunction()` to execute your code.
```
Inline code snippets for functions and method names.
- Backticks must match (one on each side).
- Code within backticks is rendered as-is.
#### Inline code with special characters
```markdown
The spread operator `...args` unpacks iterables.
Access object properties with `obj.key` or `obj['key']`.
Use the `${}` template literal syntax.
```
Inline code with operators and special characters.
- Special characters are preserved exactly in backticks.
#### Inline code in lists and emphasis
```markdown
- Use `const` instead of `var` for better scoping
- The **`Array.prototype.filter()`** method is efficient
- Store result in `const result = data.map(x => x * 2)`
```
Inline code combined with lists and emphasis.
- Code can be emphasized or nested in other structures.
**Best practices:**
- Use backticks for any code reference, variable, or function name.
- Keep inline code short and focused.
- Combine with emphasis for important code concepts.
**Common errors:**
- **Unmatched or inconsistent backticks.**: Ensure one backtick before and after code.
### Code Blocks
Create multi-line code blocks using indentation or fences.
**Keywords:** code blocks, fenced code, syntax highlighting, indented code, language identifier
#### Fenced code block with language
```markdown
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
greet('World');
```
```
Fenced code block with JavaScript syntax highlighting.
- Language identifier enables syntax highlighting.
- Triple backticks (```) fence the code block.
#### Python code block
```markdown
```python
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
print(fibonacci(10))
```
```
Fenced code block with Python syntax highlighting.
- Language identifiers vary by parser but common ones include python, javascript, etc.
#### Code block without syntax highlighting
```markdown
```
Plain text output
No syntax highlighting
Just displayed as-is
```
```
Fenced code block without language specification.
- Useful for output, logs, or plain text.
**Best practices:**
- Always specify language for better readability.
- Keep code blocks focused and self-contained.
- Use meaningful examples in documentation.
**Common errors:**
- **Inconsistent fence formatting.**: Use triple backticks (```) consistently.
### Blockquotes
Create blockquotes using > prefix for quotes and references.
**Keywords:** blockquotes, quotes, citations, references, nesting
#### Simple blockquote
```markdown
> Markdown is a simple way to format text.
> It supports various text styles and structures.
```
Basic blockquote with multiple lines.
- Use > for each line or once at the beginning of a paragraph.
#### Blockquote with formatting
```markdown
> **Important:** Always validate user input before processing.
>
> Use `input.trim()` and check length requirements.
```
Blockquote with bold text, code, and multiple paragraphs.
- Blockquotes can contain formatted text and code.
#### Nested blockquotes
```markdown
> This is the first level quote.
>
> > This is a nested quote.
> > It's indented further.
>
> Back to the first level.
```
Multi-level nested blockquotes.
- Nesting is created by adding additional > symbols.
**Best practices:**
- Use blockquotes for important notes and warnings.
- Attribute quotes to their source when possible.
- Keep quotes concise and impactful.
**Common errors:**
- **Missing > prefix on continuation lines.**: Use > for each line in a blockquote.
## Tables and Horizontal Rules
Create data tables and visual separators using Markdown syntax.
### Tables
Format tabular data using pipes and dashes.
**Keywords:** tables, data, columns, rows, separator, pipe
#### Basic table
```markdown
| Name | Age | City |
|--------|-----|-----------|
| Alice | 28 | New York |
| Bob | 32 | San Diego |
| Carol | 25 | Boston |
```
Simple table with three columns and header row.
- Pipes (|) separate columns.
- Dashes (---) create the separator row.
#### Table with alignment
```markdown
| Left | Center | Right |
|:--------|:-------:|--------:|
| Aligned | Center | Aligned |
| Left | Centered| Right |
```
Table with left, center, and right alignment.
- Left colon (:---) aligns left.
- Both colons (:---:) centers.
- Right colon (---:) aligns right.
#### Table with formatted content
```markdown
| Function | Description | Example |
|----------|-------------|---------|
| `map()` | Transforms arrays | `[1,2,3].map(x => x*2)` |
| `filter()` | **Filters** items | `arr.filter(x => x > 5)` |
| `reduce()` | Combines *all* items | `arr.reduce((a,b) => a+b)` |
```
Table with code and formatted text in cells.
- Tables can contain inline formatting like code and emphasis.
**Best practices:**
- Keep tables readable with consistent column widths.
- Use meaningful headers that describe column content.
- Limit tables to essential data only.
**Common errors:**
- **Missing pipes or incorrect alignment syntax.**: Ensure pipes separate each column and dashes align properly.
### Table Formatting
Apply formatting options within table cells.
**Keywords:** table formatting, cell styling, alignment, emphasis, code in tables
#### Table with emphasis and code
```markdown
| Feature | Status | Notes |
|---------|--------|-------|
| **Login** | ✓ | Uses `OAuth2` |
| Single Sign-On | In Progress | *Coming soon* |
| Multi-Factor Auth | ✗ | Planned for Q2 |
```
Table with bold, code, italic, and symbols.
- Mix formatting styles within cells as needed.
#### Table with links and images alt text
```markdown
| Technology | Link | Active |
|------------|------|--------|
| [React](https://react.dev) | Official Docs | Yes |
| [Vue](https://vuejs.org) | Vue.js Site | Yes |
| Angular | [Docs](https://angular.io) | In Maintenance |
```
Table with hyperlinks in cells.
- Links work within table cells.
#### Complex table layout
```markdown
| API Endpoint | Method | Required Parameters | Response |
|--------------|--------|---------------------|----------|
| `/api/users` | GET | `None` | `User[]` |
| `/api/users` | POST | `name`, `email` | `User` |
| `/api/users/:id` | PUT | `id`, `updates` | `User` |
| `/api/users/:id` | DELETE | `id` | `{ success: boolean }` |
```
Complex API documentation table.
- Tables work well for API documentation.
**Best practices:**
- Use consistent formatting across related cells.
- Keep cell content concise.
- Align related information in rows.
**Common errors:**
- **Overwhelming tables with too much formatting.**: Use formatting sparingly for emphasis only.
### Horizontal Rules
Create visual separators using horizontal line syntax.
**Keywords:** horizontal rules, separators, breaks, dividers, visual separation
#### Different horizontal rule styles
```markdown
First section content.
---
Second section with dashes.
***
Third section with asterisks.
___
Fourth section with underscores.
```
Three different styles of horizontal rules.
- All three (---, ***, ___) produce the same visual separators.
#### Horizontal rules in document structure
```markdown
# Main Document
Introduction paragraph.
---
## Section 1
Content for section 1.
---
## Section 2
Content for section 2.
```
Horizontal rules separating document sections.
- Rules provide visual breaks between content areas.
#### Minimal horizontal rule syntax
```markdown
Content above.
---
Content below.
```
Simple horizontal rule separator.
- Requires at least three characters and blank lines above/below.
**Best practices:**
- Use horizontal rules to visually separate topics.
- Use headings for actual content structure.
- Don't overuse separators; they can clutter documents.
**Common errors:**
- **Using horizontal rules instead of headings for structure.**: Use headings (H1-H6) for document hierarchy.
## Advanced Features
Learn escaping, HTML integration, and Markdown best practices.
### Escaping
Escape special characters to display them literally.
**Keywords:** escaping, backslash, special characters, literals, characters
#### Escaping special characters
```markdown
\# Not a heading
\* Not italic \*
\[Not a link\](https://example.com)
\`Not inline code\`
```
Backslash escapes prevent Markdown interpretation.
- Backslash (\\) escapes the following character.
- Common escaped characters: #, *, {, }, [, ], |, \
#### Escaping symbols in text
```markdown
This costs \$50, not $50.
Use \+ to concatenate, not +.
The \& symbol is ampersand.
C\+\+ is a programming language.
```
Escaped dollar signs, operators, and symbols.
- Most symbols need escaping only in specific Markdown contexts.
#### Escaping in code and tables
```markdown
| Character | Escaped | Purpose |
|-----------|---------|---------|
| \* | \\\* | Asterisk |
| \[ | \\\[ | Bracket |
| \\ | \\\\ | Backslash |
```
Escaping characters in table cells.
- Escaping in code blocks and tables follows Markdown rules.
**Best practices:**
- Only escape when necessary to prevent interpretation.
- Use backticks for literal code instead of escaping.
- Test special character rendering in your target renderer.
**Common errors:**
- **Over-escaping characters that don't need escaping.**: Check which characters actually need escaping in your context.
### HTML and Raw Content
Embed HTML and raw content within Markdown documents.
**Keywords:** html, raw html, entities, inline html, custom elements
#### Inline HTML tags
```markdown
This is highlighted text using HTML.
Use small text for footnotes.
Create colored text with HTML.
```
Inline HTML elements mixed with Markdown text.
- Most Markdown renderers support basic HTML tags.
- Use HTML for formatting Markdown doesn't support.
#### HTML entities and special characters
```markdown
Copyright © 2024
Registered ® Trademark
Em dash — separates thoughts
Left arrow ← navigate back
```
HTML entities for special symbols.
- Entities are useful for symbols not on keyboard.
#### HTML block elements
```markdown
This is a custom box with HTML.
Markdown formatting still works **inside**.
```
Block-level HTML with embedded Markdown.
- Most renderers support Markdown inside block HTML.
**Best practices:**
- Use Markdown features first, HTML as fallback.
- Keep HTML semantic and accessible.
- Test HTML rendering in your target platform.
**Common errors:**
- **Mixing HTML and Markdown inconsistently.**: Use Markdown primarily, HTML only when necessary.
### Best Practices
Write clean, readable, and accessible Markdown documents.
**Keywords:** best practices, standards, commonmark, readability, consistency, accessibility
#### Well-structured Markdown document
```markdown
# Project Documentation
## Overview
A brief description of the project.
## Installation
Steps to install and setup.
## Usage
Examples of how to use the project.
## Contributing
Guidelines for contributing.
```
Consistent document structure with clear hierarchy.
- Use consistent heading levels throughout.
- Organize logically with clear sections.
#### Accessible Markdown with proper alt text
```markdown
# User Guide
**Bold** for important terms, not just styling.
Code examples use backticks: `const x = 5`.
- Use lists for multiple items
- Each item is clear and concise
- Organized logically
```
Markdown with accessibility considerations.
- Always include alt text for images.
- Use semantic formatting (bold, italic for meaning).
#### CommonMark compliant Markdown
```markdown
# Introduction
This document follows CommonMark standards.
```python
# Code blocks use language identifiers
def hello():
print("Hello, World!")
```
[Links](https://example.com) are explicit
---
**Final thoughts** on Markdown compliance.
```
CommonMark compliant Markdown document.
- CommonMark is the standard for portable Markdown.
**Best practices:**
- Use consistent formatting throughout documents.
- Write for readability in both source and rendered form.
- Follow a clear document structure with headings.
- Provide descriptive alt text for all images.
- Use meaningful link text, not placeholders.
- Test documents in your target renderer.
**Common errors:**
- **Inconsistent heading levels and structure.**: Plan document hierarchy before writing.
- **Poor alt text or missing image descriptions.**: Always provide meaningful descriptions for accessibility.