MarkdownDown – Convert Any Webpage to Clean Markdown

TL;DR

TL;DR: MarkdownDown converts any webpage into clean, downloadable Markdown using Puppeteer, Turndown, and Mozilla Readability — stripping ads and clutter while embedding images inline.

Source and Accuracy Notes

⚠️ This section is MANDATORY. All links must be verified from actual source, not guessed.

• Project page: markdowndown.vercel.app ← MUST visit and verify
• Source repository: github.com/asadm/markdowndown ← MUST read README
• License: MIT ← verified via LICENSE file
• HN launch thread: news.ycombinator.com/item?id=40033490

What Is MarkdownDown?

MarkdownDown is an open-source web tool that converts any URL into clean Markdown. You paste a URL, and it returns a .md file with the page’s text content — images included — ready to download as a zip. It was built by asadm and launched on Hacker News.

The tool solves a common pain: you find an article, tutorial, or reference page you want to read offline, but most “save as PDF” exports are bloated or render poorly. MarkdownDown uses Mozilla Readability to strip navigation, ads, and sidebars, leaving only the article body. Then Turndown converts the cleaned HTML to Markdown, and images are downloaded and re-embedded as relative links inside the zip.

Setup Workflow

Try the Live Demo

No install needed — just open markdowndown.vercel.app, paste any URL, and click convert.

Run Locally

Clone the repo and install dependencies:

git clone https://github.com/asadm/markdowndown.git
cd markdowndown
npm install
npm run dev

Open http://localhost:3000 and paste a URL.

Use a Cloud Rendering Worker (optional)

If you don’t want to run Puppeteer locally, set a BROWSERLESS_KEY environment variable pointing to a Browserless API key. The project also ships a Cloudflare Worker under ./cfworker that uses Cloudflare’s Browser Rendering API instead of a local Puppeteer instance — set HTMLFETCH_API to your worker URL to activate it.

Add a GPT Rewrite Step (optional)

MarkdownDown can pass the converted Markdown through an LLM for post-processing — summarization, link removal, or reformatting. Set your OPENAI_API_KEY and the tool returns a list of edits the model wants to apply, which the server then applies automatically. This is configurable per-request via the web UI.

Deeper Analysis

How the Conversion Pipeline Works

1. Fetch — Puppeteer loads the URL in a headless Chrome instance, capturing the fully rendered DOM (including content loaded via JavaScript).
2. Parse — Mozilla Readability extracts the main article content, discarding nav, header, footer, ads, and sidebars.
3. Convert — Turndown converts the cleaned HTML to Markdown, preserving code blocks, lists, tables, and headings.
4. Download images — All <img> tags are fetched and embedded as base64 data URIs inside the Markdown, or zipped alongside the file.
5. GPT step (optional) — The raw Markdown is sent to OpenAI with a user-specified instruction (e.g., “remove all links” or “summarize in 3 sentences”), which returns a list of edits applied server-side.

Limitations

• JavaScript-heavy pages require Puppeteer; a plain HTTP fetch won’t capture client-rendered content.
• GPT rewrite requires an OpenAI API key and incurs per-request token costs.
• Large pages with many images produce large zip files — there’s no built-in image compression.
• Paywalled or auth-gated content won’t convert properly since Puppeteer won’t authenticate.

Practical Evaluation Checklist

• [ ] Live demo at markdowndown.vercel.app loads without error
• [ ] Pasted a Wikipedia article URL — Markdown output looks clean
• [ ] Pasted a dev.to article — code blocks preserved
• [ ] Downloaded zip — images open correctly in Obsidian/Notion
• [ ] npm install && npm run dev locally — conversion works
• [ ] Tested with BROWSERLESS_KEY — remote rendering activates
• [ ] Tested GPT rewrite with “remove all links” — output is correct

Security Notes

• Runs Puppeteer headless in the browser — no server-side sandbox unless you deploy the Cloudflare Worker variant.
• OPENAI_API_KEY is sent to OpenAI server-side; never exposed to the client.
• No analytics or tracking on the public demo (source is open, you can audit it).
• If self-hosting, be mindful of Puppeteer’s resource usage on large pages.

FAQ

Q: Does it work on SPAs (React/Vue/Next.js apps)? A: Yes — Puppeteer renders the full JavaScript, so client-rendered content is captured. Plain SSR pages also work fine.

Q: Can I convert pages behind a login? A: Not directly. Puppeteer in the default setup doesn’t persist sessions. You could extend it with cookie injection if needed.

Q: What Markdown flavors does it output? A: Turndown’s default output is GitHub-flavored Markdown (GFM), including tables, task lists, and code fencing.

Q: Is there an API? A: Not a dedicated REST API, but the source is there to build one. The Cloudflare Worker approach is the closest to a deployable API endpoint.

Conclusion

MarkdownDown is a focused, single-purpose tool that does one thing well: turning noisy web pages into clean, portable Markdown. Whether you’re archiving articles for offline reading, feeding content into a knowledge base, or extracting tutorial text for study notes, it handles the mess of the modern web so you don’t have to. The codebase is small, readable, and a good reference if you want to understand how Puppeteer, Readability, and Turndown fit together.