The Markdown Guide for Writers

Syntax cheat sheet

Headings

# H1 (one per page — your title)
## H2 (main sections)
### H3 (subsections)
#### H4
##### H5
###### H6 (rarely needed)

One # per heading level. A single space between the hashes and the heading text. Don't use H1 inside an article — Markdown CMSes use the post title as H1 already.

Bold and italic

**bold**
*italic*
***bold and italic***
~~strikethrough~~ (GitHub-flavored only)

Use ** for bold over __ — it's more legible and works in every flavor. Use * for italic over _ for the same reason.

Links and images

[Visible link text](https://example.com)
![Alt text](https://example.com/image.jpg)
[Reference-style link][1]

[1]: https://example.com

Reference-style links (the bottom form) are useful when the same URL is used multiple times in a long document.

Lists

- Unordered item
- Another item
  - Nested item (2-space indent)

1. Ordered item
2. Second item
   1. Nested ordered item

Pro tip: for ordered lists, you can write 1. for every line — most processors auto-renumber. This makes inserting/removing items far easier.

Code

`inline code` for a quick keyword

```
multi-line code block
```

```python
fenced code block with language
```

The triple-backtick fenced block is universally supported and lets you specify the language for syntax highlighting.

Blockquotes and horizontal rules

> This is a blockquote.
> Multi-line by repeating > on each line.

---  (three or more dashes = horizontal rule)

Tables (GitHub-flavored Markdown)

| Header | Header |
|--------|--------|
| Cell   | Cell   |
| Cell   | Cell   |

Tables are not in original Markdown but are universal in modern flavors (GitHub, Notion, Obsidian, every static-site generator).

Converting between Markdown and HTML

Most CMSes accept either Markdown or HTML, but some force you into one. The two most common workflows:

• Wrote in Markdown, need HTML for an HTML-only CMS? Use our Markdown → HTML Converter. Paste the Markdown, copy the HTML, drop into your CMS.
• Migrating content out of an HTML-only CMS into a Markdown system (Notion, Obsidian, GitHub, Hugo)? Use our HTML → Markdown Converter. Strips inline styles, classes, and noise — leaves clean Markdown.

Markdown across the ecosystem

When NOT to use Markdown

Markdown is great for prose and structure. It's a poor fit for:

• Visual / design-heavy content. If you're laying out a magazine page, use a design tool, not Markdown.
• Forms, surveys, complex tables, and styled content. Markdown can't express what HTML+CSS can. If you need precise control over fonts, colors, columns, or interactive elements, write HTML directly.
• Mathematical notation. Some processors support LaTeX inside Markdown ($\\alpha$), but support is inconsistent. For heavy math, a LaTeX-first tool wins.
• Highly-structured data. Use JSON / YAML / TOML, not Markdown lists.

Frontmatter — the secret weapon

Most static-site generators support YAML frontmatter at the top of every Markdown file. This is metadata about the post — title, date, tags, author — that the generator reads at build time.

---
title: My First Blog Post
date: 2026-05-07
author: Jane Smith
tags: [writing, productivity]
---

# My First Blog Post

Body of the post in Markdown…

Different generators expect different keys. Hugo uses title, date, draft; Jekyll uses layout, title, permalink; Eleventy uses permalink, tags, layout. Read your generator's docs for specifics.

Free tools used in this guide

• Markdown → HTML Converter — convert Markdown to clean semantic HTML.
• HTML → Markdown Converter — extract clean Markdown from rendered HTML, perfect for content migration.
• Find & Replace — useful for batch-converting one Markdown variant to another.
• Word Counter — your draft's word count and readability score.
• Character Counter — character counts for the times Markdown documents have hard limits (e.g. GitHub README badges).

Frequently asked questions