Markdown Guide for Writers and Developers

Markdown is the closest thing the internet has to a universal writing format. It's used in GitHub READMEs, Notion documents, Slack messages, documentation sites, blog posts, and developer notes. Learn it once and you'll use it everywhere — for the rest of your career.

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. The core idea: write in plain text using simple punctuation conventions, and it renders to beautifully formatted HTML.

This **bold text** and *italic text* render instantly.

Renders as: This bold text and italic text render instantly.

The raw text is still perfectly readable — even before rendering.

Basic syntax

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Use headings to create a document hierarchy. # H1 is typically the page title — use only one per document.

Emphasis

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~

Lists

Unordered list:
- Item one
- Item two
  - Nested item (indent with 2 spaces)
  - Another nested item
- Item three

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

Links and images

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

![Alt text for image](https://example.com/image.jpg)
![Alt text](./local-image.png "Optional title")

Blockquotes

> This is a blockquote.
> It can span multiple lines.

> You can nest blockquotes:
> > Like this.

Horizontal rule

---

(Three or more dashes, asterisks, or underscores on their own line)

Code blocks

Inline code uses single backticks:

Use the `console.log()` function for debugging.

Fenced code blocks use triple backticks with an optional language identifier for syntax highlighting:

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

Supported languages include javascript, typescript, python, bash, sql, json, yaml, css, html, go, rust, and dozens more — depending on the renderer.

Tables

Markdown tables use pipe characters and dashes:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A   | Cell B   | Cell C   |
| Cell D   | Cell E   | Cell F   |

Align columns with colons in the separator row:

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Tables are part of GitHub Flavored Markdown (GFM), not standard Markdown. They work in GitHub, VS Code, most documentation platforms, and MDX.

Task lists (GFM)

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Add images

Renders as interactive checkboxes on GitHub. Widely supported in modern Markdown renderers.

Markdown flavors

Original Markdown is intentionally minimal. Extensions have proliferated:

Flavor	Used in	Key additions
CommonMark	Many platforms	Standardized spec
GitHub Flavored (GFM)	GitHub, GitLab	Tables, task lists, strikethrough, autolinks
MDX	React sites	JSX components inside Markdown
Pandoc Markdown	Academic docs	Footnotes, citations, math
MultiMarkdown	macOS tools	Tables, metadata, footnotes

When in doubt, use GFM — it's the most widely supported extended flavor.

Front matter

Many Markdown processors support YAML front matter at the top of a file for metadata:

---
title: "My Article Title"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---

# Article content starts here

Front matter is parsed separately from the document body and used for things like page titles, dates, and SEO metadata.

MDX: Markdown + JSX

MDX is Markdown that can contain React components. It's ideal for documentation and blog posts in React-based sites (Next.js, Gatsby, Astro):

import { Alert } from '../components/Alert'

## Important note

<Alert type="warning">
  This feature is deprecated in v3.
</Alert>

Regular **Markdown** content continues below.

This blends the simplicity of Markdown with the power of interactive components.

Escaping special characters

Prefix special Markdown characters with a backslash to render them literally:

\*not italic\*
\# not a heading
\[not a link\]

Tips for better Markdown documents

1. One sentence per line — Makes diffs cleaner in Git; renders identically since Markdown ignores single newlines.
2. Blank line between blocks — Always leave a blank line between paragraphs, headings, lists, and code blocks.
3. Consistent list markers — Pick - or * for unordered lists and stick to it across a project.
4. Reference links for repeated URLs — Define once, use many times:

   See the [documentation][docs] and [changelog][docs].
   [docs]: https://example.com/docs
   

5. Alt text for every image — Essential for accessibility and SEO.

Checking readability

Markdown makes it easy to write — but easy writing can produce hard-to-read text. Use our Readability Score tool to check Flesch-Kincaid grade level, sentence complexity, and passive voice usage. Aim for clear, concise language at a Grade 8–10 reading level for general audiences.

Markdown is one of those tools that takes 10 minutes to learn and pays dividends for a lifetime. Start writing in it today — your future collaborators (and future self) will thank you.