The Complete Markdown Guide (2026 Edition)

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. The idea is simple: you write plain text with a few formatting conventions, and it gets converted to clean HTML. No mouse needed, no toolbar, no bloated interface.

I write all my documentation, blog posts, notes, and even this guide in markdown. Once you get used to it, going back to a visual editor feels like driving a car with square wheels. The syntax is intuitive — you probably already know most of it without realizing: # makes a heading, **bold** makes text bold, and *italic* makes it slanted.

Ready to try it? Open MDtoTEXT — a free online markdown editor with live preview — and follow along.

Basic Syntax

Here's everything you need to write 90% of your documents. If you only learn this section, you'll be fine.

Headings

Six levels, one hash per level:

# Heading 1 (page title)
## Heading 2 (major section)
### Heading 3 (subsection)
#### Heading 4
##### Heading 5
###### Heading 6

Text Formatting

**bold** or __bold__
*italic* or _italic_
~~strikethrough~~
`inline code`
***bold and italic***

Links

[Link text](https://example.com)
[Link with title](https://example.com "Title on hover")
<https://autolink.com>

Images

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

Lists

- Unordered item
- Another item
  - Nested (4 spaces indent)

1. Ordered item
2. Another
3. And another

Blockquotes

> This is a quote.
> It can span multiple lines.
>> Nested quotes work too.

Horizontal Rules

---
***

Need more examples? See the Markdown Cheat Sheet for a full reference.

Advanced Syntax

Task Lists

Interactive checkboxes — works in most modern editors including MDtoTEXT, GitHub, and Obsidian.

- [x] Task completed
- [ ] Task pending
- [ ] Another to-do

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: The footnote text appears at the bottom.

Definition Lists

Term One
: Definition for term one

Term Two
: Definition for term two

Strikethrough

~~This text is crossed out~~

Highlighting

==highlighted text==

For a complete syntax reference with more examples, read the Markdown Cheat Sheet.

Tables

Tables are the one thing in markdown that feels a bit awkward. You align columns with pipes and dashes. But once you get the hang of it, they're faster than building HTML tables by hand.

| Name  | Role    | Hobby     |
|-------|---------|-----------|
| Alice | Writer  | Painting  |
| Bob   | Dev     | Climbing  |
| Carol | Design  | Pottery   |

You can also control alignment:

| Left   | Center | Right |
|:-------|:------:|------:|
| text   | text   | text  |

Pro tip: use a table generator for anything with more than 4 columns. I do. Life's too short to align pipes by hand.

Code Blocks & Syntax Highlighting

Fenced code blocks with language tags tell the renderer which syntax highlighting theme to use. Most editors support dozens of languages.

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

```python
def greet(name):
    return f"Hello, {name}!"
```

```css
.container {
  display: flex;
  gap: 1rem;
}
```

In MDtoTEXT, code highlighting uses highlight.js with the Atom One Dark theme. It supports 40+ languages out of the box.

Diagrams with Mermaid

This is one of my favorite features. You can create flowcharts, sequence diagrams, Gantt charts, class diagrams, and more — all inside your markdown using Mermaid syntax. Just tag your code block with mermaid.

```mermaid
graph TD
    A[Write markdown] --> B{Live preview?}
    B -->|Yes| C[See result instantly]
    B -->|No| D[Guess and refresh]
    C --> E[Happy developer]
```

This renders as an actual diagram in editors that support Mermaid — MDtoTEXT, GitHub, Obsidian, and many others. I use Mermaid for architecture diagrams, user flows, and even project planning.

Other diagram types you can create:

• Sequence diagrams — perfect for API flows
• Class diagrams — for software architecture
• Gantt charts — project timelines
• Pie charts — simple data visualization
• Mind maps — brainstorming

LaTeX Math

If you write technical content with formulas, LaTeX math rendering is a lifesaver. Wrap inline math in single dollar signs and display math in double dollar signs.

Inline: $E = mc^2$

Display:
$$\int_{a}^{b} x^2 dx$$

MDtoTEXT uses MathJax to render LaTeX. It supports everything from basic algebra to complex integrals and matrices.

Best Markdown Editors in 2026

I've tested dozens of markdown editors over the years. Here's a quick comparison of the ones I actually use:

For a detailed breakdown with pros, cons, and personal experience with each one, read Best Markdown Editors in 2026: 12 Editors Tested.

Markdown vs Rich Text Editors

This is a debate I've had with countless colleagues. Rich text (Word, Google Docs, WordPress block editor) gives you visual formatting, but at a cost: bloat, vendor lock-in, and fragile formatting that breaks during copy-paste.

Markdown gives you portability, speed, and clean output. The tradeoff is you don't see the formatting as you type — unless you use a live preview editor like MDtoTEXT.

My rule of thumb: if it's longer than a paragraph and might need to outlive the platform, write it in markdown. Read more in Markdown vs Rich Text Editors: Which One Should You Use?

Markdown for Blogging

More and more bloggers are switching to markdown. Ghost and Dev.to support it natively. Static site generators like Hugo and Jekyll use it as their source format. Even WordPress has markdown plugins.

Why? Because markdown decouples your content from your platform. You can write in any editor, store files in Git, and publish anywhere. No more fighting with WordPress's block editor or losing formatting during migration.

I wrote about my personal experience switching in I Write All My Blog Posts in Markdown Now. Here's Why.

Markdown for Developers

Markdown is everywhere in software: README files, documentation, API specs, issue trackers, wikis. GitHub, GitLab, Bitbucket — all use markdown for rendering code repositories.

For developers, markdown is non-negotiable. It integrates with version control, supports code blocks with syntax highlighting, and works with every CI/CD pipeline. I've written entire API documentations in markdown and converted them to HTML, PDF, and even EPUB.

Deep dive: Markdown for Developers: Why It's Still the Best Documentation Tool

Markdown to HTML Converters

Need to convert markdown to HTML? You have options:

• Online: MDtoTEXT — free, private, live preview. Your data stays in your browser.
• CLI: Pandoc — the Swiss Army knife of document conversion. Supports markdown to HTML, PDF, DOCX, LaTeX, and more.
• JavaScript: marked, remark, showdown — libraries you can embed in your own apps.
• Static site generators: Hugo, Jekyll, Next.js — they all convert markdown to HTML automatically.

Full comparison: Best Online Markdown to HTML Converters

Markdown Tips & Best Practices

After years of writing markdown daily, here's what I've learned:

• Always put a blank line before headings and code blocks. Some renderers are picky about this.
• Use asterisks for bold/italic, not underscores. Asterisks are easier to spot in raw text.
• One space after hash, not zero. #Heading doesn't work but # Heading does.
• Keep lines under 80 characters. It makes diff reviews in Git much cleaner.
• Use reference-style links for repeated URLs. Cleaner source, easier to update.
• Preview before publishing. Different renderers handle edge cases differently (like nested lists or table alignment).
• Store files in Git. Version control for your writing is a superpower.

Start Writing Markdown Today

The best way to learn markdown is to write markdown. Open MDtoTEXT in your browser — it's free, no signup, and the live preview shows you exactly what your formatting looks like. You'll be fluent in an hour.