The Complete Markdown Guide: From Basic Syntax to Advanced Formatting

Markdown was created in 2004 by John Gruber with one goal: write formatted text using plain characters that anyone can read even without rendering. Two decades later, it powers GitHub READMEs, Slack messages, Notion pages, Jekyll blogs, documentation sites, and hundreds of other platforms. If you write on the web, you use Markdown whether you realize it or not.

The syntax is minimal enough to learn in twenty minutes and powerful enough to format entire books. Try any of the examples below in the Markdown Editor, which renders your text as you type.

Basic Text Formatting

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`

Renders as: bold text, italic text, bold and italic, strikethrough, inline code.

Underscores also work: _italic_ and __bold__. Most people prefer asterisks because they work consistently regardless of surrounding characters. Underscores inside words (like some_variable_name) can sometimes be misinterpreted by parsers.

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

The number of # symbols determines the heading level. Always put a space between the # and the text. Most style guides recommend using only H1 through H3 for readability; if you need H4 or deeper, consider restructuring your content.

Best practice: Use exactly one H1 per document (the title). Use H2 for major sections and H3 for subsections. Skip levels rarely; jumping from H2 to H4 confuses screen readers and accessibility tools.

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")

![Alt text](image.jpg)
![Alt text](image.jpg "Optional title")

Links use square brackets for the text and parentheses for the URL. Images are the same but with an exclamation mark prefix. The alt text for images is not optional decoration; it is essential for accessibility and SEO.

Reference-style links keep long URLs from cluttering your text:

Read the [documentation][docs] for details.

[docs]: https://example.com/documentation

The reference definition can go anywhere in the document. This is especially useful in long documents with many repeated links.

Lists

Unordered:
- Item one
- Item two
  - Nested item
  - Another nested

Ordered:
1. First step
2. Second step
3. Third step

Task list (GFM):
- [x] Completed task
- [ ] Pending task

You can use -, *, or + for unordered lists. Pick one and be consistent. Nested items require two or four spaces of indentation (parsers vary). Task lists are a GitHub Flavored Markdown (GFM) extension and may not render in all parsers.

Code Blocks

Inline code uses single backticks: `variable`. Block code uses triple backticks with an optional language identifier for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Supported languages vary by platform but typically include: javascript, python, java, css, html, bash, json, yaml, sql, go, rust, typescript, ruby, php, c, cpp, csharp, swift, and kotlin.

Four-space indentation also creates code blocks in standard Markdown, but fenced blocks with language tags are preferred because they support syntax highlighting.

Tables

| Header 1 | Header 2 | Header 3 |
|----------|:--------:|---------:|
| Left     | Center   |    Right |
| aligned  | aligned  |  aligned |

Colons in the separator row control alignment: left colon for left-align (default), both colons for center, right colon for right-align. Tables do not need to be visually aligned in the source; parsers ignore extra spaces. But aligning them makes the source readable.

Tables are part of GFM and most extended Markdown parsers. Standard Markdown (as defined by Gruber) does not include tables.

Blockquotes

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > And be nested.

Blockquotes are commonly used for quotations, callouts, and notes. Some documentation systems use them with special prefixes for admonitions:

> **Note:** This is important.
> **Warning:** Be careful here.

Horizontal Rules

---
***
___

Three or more hyphens, asterisks, or underscores on their own line create a horizontal rule. All three produce the same output.

Converting Between Markdown and HTML

Sometimes you need to go from one format to the other. The HTML to Markdown converter is useful when you want to take existing web content and edit it in Markdown format. The Markdown to HTML converter goes the other direction, rendering your Markdown as clean HTML that you can paste into a CMS or email template.

Extended Syntax and Flavors

The original Markdown specification is deliberately minimal. Various extensions add features:

GitHub Flavored Markdown (GFM): Tables, task lists, strikethrough, autolinked URLs, and fenced code blocks. The most widely used extension.

CommonMark: A formalized specification that resolves ambiguities in the original Markdown spec. Most modern parsers are CommonMark-compatible.

MDX: Markdown with JSX. Used in React-based documentation sites (Docusaurus, Next.js). Lets you embed interactive components in Markdown documents.

Obsidian/Roam: Double-bracket links ([[Page Name]]) for wiki-style note linking. Not standard Markdown but popular in personal knowledge management.

Markdown Best Practices

• One sentence per line. In source files (especially those tracked with Git), putting each sentence on its own line makes diffs cleaner and merges easier. The rendered output still shows continuous paragraphs.
• Blank lines matter. Paragraphs require a blank line between them. Without the blank line, consecutive lines merge into a single paragraph.
• Use ATX headings. The # Heading style is universally supported and clearer than the Setext style (underlined with = or -).
• Escape special characters. Use backslashes to render literal asterisks, brackets, and other Markdown syntax characters: \*not italic\*.
• Test in the target platform. Markdown rendering varies between GitHub, GitLab, Slack, and static site generators. The Markdown Editor uses a standard CommonMark parser, which matches most platforms.

Markdown's strength is that it gets out of the way. You think about content, not formatting. Once the syntax becomes muscle memory, which takes about a week of regular use, you will find yourself reaching for Markdown even in contexts that do not support it, just because the mental model is that natural.