Markdown Complete Guide: Syntax, Tips & Best Practices

March 29, 2026 · 12 min read

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you write formatted text using plain text syntax that is easy to read and write. Instead of clicking buttons in a word processor or writing HTML tags, you use simple characters like # for headings, ** for bold, and - for lists.

Markdown has become the standard for technical writing, documentation, README files, blog posts, and note-taking. Platforms like GitHub, Reddit, Stack Overflow, Discord, and Notion all support Markdown natively.

The beauty of Markdown is that the source text remains readable even without rendering. A Markdown document looks clean in any text editor, unlike HTML which is cluttered with tags.

Why Use Markdown?

• Speed — Writing **bold** is faster than <strong>bold</strong>
• Portability — Plain text files work everywhere, on every OS and editor
• Version control — Git diffs are clean and meaningful with Markdown
• Focus — No formatting toolbar distractions; just write
• Conversion — Easily converts to HTML, PDF, DOCX, and other formats

Headings

Headings use the # symbol. The number of hashes determines the heading level (1-6):

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

Always put a space after the # symbol. Most Markdown processors require it. Use heading levels sequentially — don't skip from H1 to H3. This matters for accessibility and SEO.

Text Formatting

Lists

Unordered Lists

Use -, *, or + followed by a space. Nest with 2-space indent:

- First item
- Second item
  - Nested item
- Third item

Ordered Lists

1. First item
2. Second item
3. Third item

Task Lists (GFM)

- [x] Completed task
- [ ] Incomplete task

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Title")
![Alt text](image.png)

Always include descriptive alt text for images. Use our Markdown to HTML converter to preview how your links render.

Code Blocks

Inline code uses backticks: `variable`. Fenced code blocks use triple backticks with a language identifier:

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

Common languages: javascript, python, html, css, bash, json, sql, typescript.

Tables

| Feature     | Markdown | HTML   |
|-------------|----------|--------|
| Readability | High     | Low    |
| Speed       | Fast     | Slow   |

Alignment: :--- left, :---: center, ---: right.

Blockquotes and Horizontal Rules

> This is a blockquote.
> > Nested blockquotes work too.

---

Extended Syntax

Footnotes

Text with a footnote.[^1]
[^1]: Footnote content.

Definition Lists

Term
: Definition of the term

HTML in Markdown

When Markdown syntax is not enough, use raw HTML. Most processors support <details>, <summary>, <kbd>, and other tags.

Markdown Flavors

Best Practices

1. One sentence per line — Makes diffs cleaner in version control
2. Consistent heading hierarchy — Never skip levels
3. Alt text on images — Required for accessibility
4. Blank lines around blocks — Headings, lists, code blocks need them
5. Use fenced code blocks — Clearer than indented code
6. Lint your Markdown — markdownlint catches common issues
7. Preview before publishing — Use TxtTool's Markdown Editor