Notion to Markdown in 5 minutes

Markdown is the lingua franca of docs, blogs, and GitHub READMEs.

Notion is where those words often start.

Moving content from blocks to plain‑text syntax shouldn’t take longer than brewing coffee.

Below are three routes—each live in about five minutes.

Why bother with Markdown

• Works everywhere – GitHub, Hugo, Jekyll, VS Code all read .md natively [1].

• Version‑control‑friendly – Two characters changed? Git diff shows two lines.

• Future‑proof – No vendor lock‑in; pure text lasts.

Method 1 — Native Notion Export (fast & built‑in)

1. Open any page or database.

2. Click … → Export → Markdown & CSV [2].

3. Choose Include sub‑pages if you need nested docs.

4. Download the zip and extract. Each Notion page appears as page.md; images land in an assets folder.

Pros

✔️ Zero installs.

✔️ Keeps headings, lists, tables (as HTML).

✔️ Bundles attachments.

Cons

❌ Manual—no incremental updates.

❌ Table blocks export as HTML, not pipe tables.

Method 2 — Quick “Copy as Markdown” shortcut (one‑off snippets)

Need a single section, not the whole page?

1. Highlight the blocks you want.

2. Hit ⌘/Ctrl + Shift + C. Notion copies cleaned Markdown to clipboard [3].

3. Paste into VS Code, GitHub issue, or any editor.

Pros

✔️ Instant—no zip files.

✔️ Keeps inline code, bold, lists.

✔️ Perfect for README chunks or blog intros.

Cons

❌ No images.

❌ Still manual for large docs.

Method 3 — Automated CLI with notion2md (set‑and‑forget)

Great when you version docs in a git repo and want nightly exports.

1. Install Node CLI:

npm i -g

1. Get an integration token – Notion → Settings → Integrations → New integration [4].

2. Share target pages/databases with the integration.

3. Run:

notion2md <page‑id> -t <token> -o

1. Add to package.json scripts or a GitHub Action for auto‑sync.

Pros

✔️ Incremental—rerun anytime.

✔️ Converts tables to pipe syntax.

✔️ Supports image download, front‑matter, code‑block languages.

Cons

❌ Needs Node/npm.

❌ One-time setup but then hands‑free.

Bonus – Pandoc cleanup (optional)

If you dislike HTML tables, pipe the markdown through Pandoc:

pandoc page.md -t gfm -o

Adds GitHub‑flavored tables and smart punctuation.

Quick tips & gotchas

• Notion exports emojis in file names; some static‑site generators dislike them—rename if needed.

• Large pages break into multiple .md plus _assets—keep folder structure when moving.

• Use Relational links sparingly—they export as plain URLs, not wiki links.

Five‑minute takeaway

• One‑off page? Built‑in export.

• Snippet? Copy as Markdown.

• Repo sync? notion2md CLI on a cron.

Markdown in hand, you’re free to publish anywhere—Hugo blog, GitBooks, or the README that ships with your next project.

Sources

[1] GitHub Docs – About README.md: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

[2] Notion Help – Export content: https://www.notion.so/help/export-operation

[3] Notion shortcut guide – Copy as Markdown: https://www.notion.so/help/keyboard-shortcuts#copy

[4] Notion Developers – Getting started with the API: https://developers.notion.com/docs/getting-started

[5] notion2md GitHub repo: https://github.com/koraykoska/notion2md