Complete syntax reference + free online editor

Markdown Documentation:Write, Preview & Share

The complete guide to writing Markdown documentation — with a syntax reference, live examples, and a free online editor to try everything instantly. No Git. No deploy. Just write and share.

Write Markdown docs — freeJump to syntax guide

Why Markdown

Why write documentation in Markdown?

📝

Plain text — always portable

Markdown is just plain text. It opens in any editor, works on any operating system, and never locks you into a proprietary format. Your documentation stays yours forever.

🔀

Version-control friendly

Because Markdown is plain text, Git can diff it line by line. Track every change, review edits in pull requests, and roll back to any version — just like code.

⚡

Faster to write

Markdown lets you format without touching the mouse. A few symbols — # for a heading, ** for bold, ``` for code — is far quicker than a rich-text toolbar.

🌍

Renders everywhere

GitHub, GitLab, Notion, Slack, Reddit, and thousands of other tools understand Markdown. Write once, read beautifully anywhere.

Syntax Reference

Markdown syntax guide

Every element you need to write great documentation.

Headings

Use # symbols to create headings. One # gives the largest heading (H1), ## gives H2, and so on up to H6.

Markdown

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

Rendered

Heading 1

Heading 2

Heading 3

Bold and Italic

Wrap text in ** for bold, * for italic, or *** for bold italic.

Markdown

**bold text**
*italic text*
***bold and italic***

Rendered

bold text
italic text
bold and italic

Lists

Use - or * for unordered lists. Use 1. 2. 3. for ordered lists. Indent with 2 spaces for nested lists.

Markdown

- Item one
- Item two
  - Nested item

1. First
2. Second

Rendered

  • Item one
  • Item two
    • Nested item
  1. First
  2. Second

Links and Images

Links use [text](url). Images use ![alt text](url). Both support an optional title in quotes.

Markdown

[Visit markpad](https://markpad.app)
![Logo](https://markpad.app/logo.svg "markpad logo")

Rendered

Visit markpad
![image](url) → renders image

Code

Use backticks for inline code. Use triple backticks with a language name for fenced code blocks with syntax highlighting.

Markdown

Inline: `const x = 1`

```typescript
function greet(name: string) {
  return `Hello, ${name}!`
}
```

Rendered

Inline: const x = 1

function greet(name: string) {
  return `Hello, ${'{'}name{'}'}`
}

Tables

Create tables using | separators and a header row with --- dividers. Use :--- for left, ---: for right, and :---: for centre alignment.

Markdown

| Name    | Role     |
|---------|----------|
| Alice   | Designer |
| Bob     | Engineer |

Rendered

NameRole
AliceDesigner
BobEngineer

Blockquotes

Use > at the start of a line to create a blockquote. Nest them with >>.

Markdown

> "The best documentation is
> the one people actually read."
>
> — Someone wise

Rendered

"The best documentation is the one people actually read."
— Someone wise

Task Lists

GitHub Flavored Markdown supports task lists using - [ ] for incomplete and - [x] for complete items.

Markdown

- [x] Write the spec
- [x] Get review
- [ ] Ship it

Rendered

  • ✅ Write the spec
  • ✅ Get review
  • ☐ Ship it
Try all of this live in the editor

Use cases

What do people write with Markdown documentation?

📝

PRDs & Specs

Write product requirement documents in Markdown and share a polished, readable link with your team instantly.

🔁

RFCs & ADRs

Document architecture decisions and proposals. Markdown formatting keeps them version-control-friendly and readable.

📖

README files

Draft and preview README files for your projects before committing. markpad renders them exactly as GitHub would.

🔌

API documentation

Document API endpoints, request/response schemas, and code examples with syntax-highlighted fenced code blocks.

🗒️

Meeting notes

Capture meeting notes, action items, and decisions in Markdown. Publish a link for the whole team.

📚

Knowledge bases

Build living documentation pages that auto-generate a table of contents from your headings.

Comparison

markpad vs other documentation tools

FeaturemarkpadNotionGoogle DocsGitBook
No sign-up required✅❌❌❌
Live Markdown preview✅⚠️ partial❌✅
Instant shareable link✅✅✅✅
KaTeX math support✅✅❌❌
Mermaid diagrams✅❌❌❌
No Git / deploy needed✅✅✅❌
Export to PDF✅✅✅✅
Free tier✅✅ limited✅⚠️ limited

FAQ

Questions about Markdown documentation

What is Markdown documentation?

Markdown documentation is technical or instructional content written using Markdown syntax — a lightweight plain-text formatting language. Authors use symbols like # for headings, ** for bold, and ``` for code blocks to add structure, and the Markdown is then rendered into clean HTML for reading. It is widely used for README files, software documentation, API references, and knowledge bases.

Why use Markdown for documentation instead of Word or Google Docs?

Markdown documentation has several advantages over rich-text editors: it is plain text so it works perfectly with version control (Git), it renders identically across all tools, it is portable and future-proof, and it keeps writers focused on content rather than formatting. Markdown files are also easy to search, diff, and automate.

How do I share Markdown documentation online?

With markpad, sharing Markdown documentation online is instant. Write your document in the editor, click 'Share', and you get a public URL with a designed reading experience — automatic table of contents, reading progress bar, syntax-highlighted code, and light/dark/sepia themes. No Git repository, static site generator, or deployment pipeline required.

Can a team collaborate on Markdown documentation in markpad?

markpad is currently optimised for individual writers and solo documentation workflows. Each document gets its own shareable public link, making it easy to share with a team for review. Full real-time collaboration (multiple cursors) is on the roadmap.

What's the difference between Markdown and HTML?

Markdown is a human-readable writing syntax that converts to HTML. In HTML you'd write <strong>bold</strong>; in Markdown you write **bold**. Markdown is faster to write, easier to read in raw form, and less error-prone. markpad converts your Markdown to HTML in real time so you see the final rendered output as you type.

Looking for a quick Markdown online editor to get started right now?

Try the free online Markdown editor

markdown documentation · free · instant

Write your docs in Markdown. Share in seconds.

No Git repository. No static site generator. No deployment. Just open the editor, write your Markdown documentation, and share a beautiful link.

Start writing documentation — free