Markdown: The Writing Format That Powers the Web

When you write a README file on GitHub, format a message in Slack, or write a post on Reddit, you are using Markdown. It is the most widely adopted lightweight markup language in the world, yet many people use it by feel — typing **bold** because they once saw it work, without fully understanding the syntax.

This guide covers the complete Markdown specification, explains why it became the standard for technical writing, and gives you practical examples for every formatting element.

What Is Markdown?

Markdown is a plain-text formatting syntax created by John Gruber in 2004. The goal was to allow people to write using an easy-to-read, easy-to-write plain text format that could be converted to structurally valid HTML.

The key insight behind Markdown: formatting conventions that writers already used naturally in plain-text emails — **bold**, # headings, - list items — could be formalized into a consistent, parseable syntax.

Today, Markdown is used in:

• Code repositories: GitHub, GitLab, Bitbucket (README.md, pull request descriptions, issue comments)
• Documentation: MkDocs, Docusaurus, GitBook, Confluence
• Static site generators: Hugo, Jekyll, Next.js (MDX), Gatsby
• Note-taking apps: Obsidian, Notion, Bear, Typora
• Messaging platforms: Slack, Discord, Microsoft Teams (partial support)
• Email tools: many newsletters and email editors support Markdown input

Headings

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

Headings map directly to HTML <h1> through <h6>. Use heading levels hierarchically — <h1> for the page title, <h2> for major sections, <h3> for subsections. Never skip levels (don't use <h3> directly under <h1>).

Emphasis

**bold text**
__also bold__

*italic text*
_also italic_

***bold and italic***

~~strikethrough~~

Bold is used for important terms and key points. Italic for titles (books, films), technical terms, or gentle emphasis. Use emphasis sparingly — if everything is bold, nothing stands out.

Lists

Unordered lists use -, *, or +:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered lists use numbers followed by a period:

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

The actual numbers don't matter in most Markdown parsers — you can use 1. for every item and the renderer will number them correctly. This is useful when you frequently reorder steps.

Task lists (GitHub Flavored Markdown):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another pending item

Links and Images

Inline link:

[link text](https://universalwebtoolkit.com)
[link with title](https://universalwebtoolkit.com "Universal Web Toolkit")

Reference link (useful when the same URL appears multiple times):

See the [Universal Web Toolkit][uwt] for free online tools.

[uwt]: https://universalwebtoolkit.com

Image:

![alt text](image.png)
![alt text](image.png "Optional title")

The ! before [ is the only difference between an image and a link. The alt text is important for accessibility — it describes the image for screen readers.

Code

Inline code uses single backticks:

Use the `console.log()` function to debug.

Code blocks use triple backticks with an optional language identifier:

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

The language identifier (javascript, python, bash, json, css, etc.) enables syntax highlighting in GitHub, documentation sites, and most Markdown editors.

Indented code blocks (4 spaces or 1 tab) are the original Markdown syntax but are less common now that fenced code blocks are universally supported.

Blockquotes

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

> Nested quotes use:
>> A second `>` character.

Blockquotes are useful for quoting external sources, pulling out important callouts, or representing speech.

Tables (GitHub Flavored Markdown)

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Column alignment using colons in the separator row:

| Left    | Center   | Right   |
|:--------|:--------:|--------:|
| aligned | centered | aligned |

Tables are not part of the original Markdown spec but are supported by GitHub Flavored Markdown (GFM) and most modern parsers.

Horizontal Rules

Three or more hyphens, asterisks, or underscores on a line by themselves:

---
***
___

They all render as <hr> (horizontal rule). The --- version is most commonly used.

Escaping Special Characters

Use a backslash to escape any Markdown character when you want to display it literally:

\*This is not italic\*
\`This is not code\`
\# This is not a heading

Special characters that need escaping in Markdown: \ * _ { } [ ] ( ) # + - . !

HTML in Markdown

Most Markdown parsers allow raw HTML inline:

This has a <span style="color: red">red word</span> in it.

<div class="callout">
  This is a custom callout block.
</div>

This is useful for elements Markdown cannot express natively (centered text, custom styling, colored text), though it reduces portability between parsers.

CommonMark and Flavors

The original Markdown specification by John Gruber had many ambiguities. Several flavors have emerged to address them:

• CommonMark — a standardized, unambiguous specification used by many modern parsers
• GitHub Flavored Markdown (GFM) — CommonMark plus tables, task lists, strikethrough, and autolinks
• MDX — Markdown with embedded JSX components, used in Next.js and Gatsby documentation
• Pandoc Markdown — extended Markdown for academic writing (footnotes, citations, math)

For most purposes, GFM is the safest target — it's what GitHub, the world's most-used code platform, renders.

Previewing Markdown Live

Writing Markdown in a plain text editor without a preview can be disorienting. Our Markdown Previewer tool renders your Markdown to HTML in real time as you type, with GitHub Flavored Markdown support including tables and task lists.

This is ideal for:

• Drafting GitHub README files and seeing exactly how they'll look
• Writing documentation without a full local setup
• Learning Markdown by experimenting with syntax and seeing immediate results
• Checking that complex table formatting renders correctly

Markdown for Technical Documentation

For developer documentation specifically, Markdown combined with a static site generator is the gold standard workflow:

1. Write content in .md files with clear structure
2. Add code blocks with language identifiers for syntax highlighting
3. Use tables for API parameter documentation
4. Include images and diagrams with descriptive alt text
5. Generate a searchable, navigable website with a tool like Docusaurus or MkDocs

This approach keeps documentation in version control alongside code, making it easy to update docs in the same pull request as the code changes they describe.

Summary

Markdown is the lingua franca of technical writing. Its simplicity is its power — it is readable as raw text, renders beautifully as HTML, and is supported everywhere from GitHub to Notion to email newsletters.

Key takeaways:

• Headings: #, ##, ### through ######
• Bold: **text**, Italic: *text*, Strikethrough: ~~text~~
• Lists: - for unordered, 1. for ordered, - [ ] for tasks
• Links: [text](url), Images: ![alt](url)
• Code: backticks for inline, triple backticks for blocks
• Tables and task lists are GFM extensions (supported on GitHub)
• Preview your Markdown live with the Markdown Previewer tool