markdown.new
Use markdown.new to turn public URLs or files into Markdown, crawl a site section into one Markdown document, or use the hosted editor utilities.
Verified against the live service on April 9, 2026 with direct curl requests, browser automation, and failure-case probes.
Decision Tree
What are you trying to do?
Convert one public page or API response into Markdown
- Read
references/url-conversion.md
Convert a remote file URL or upload a local file
- Read
references/file-conversion.md
Crawl multiple same-site pages and fetch one combined Markdown result
Use the hosted UI pages or the live editor
- Read
references/editor.md
Debug odd behavior, rate limits, query-string edge cases, or bad responses
- Read
references/gotchas.md
Quick Reference
| Task |
Command or Route |
Read |
| Convert one page to Markdown |
curl -s 'https://markdown.new/https://example.com' |
references/url-conversion.md |
| Convert one page to JSON |
curl -s 'https://markdown.new/https://example.com?format=json' |
references/url-conversion.md |
| Force browser rendering |
curl -s -X POST 'https://markdown.new/' -H 'Content-Type: application/json' -d '{"url":"https://example.com","method":"browser"}' |
references/url-conversion.md |
| Convert a remote file URL |
curl -s 'https://markdown.new/https://raw.githubusercontent.com/github/gitignore/main/README.md?format=json' |
references/file-conversion.md |
| Upload a local file |
curl -s -X POST 'https://markdown.new/convert' -F 'file=@notes.pdf' |
references/file-conversion.md |
| Start a crawl job |
curl -s -X POST 'https://markdown.new/crawl' -H 'Content-Type: application/json' -d '{"url":"https://docs.example.com","limit":50}' |
references/crawl.md |
| Poll crawl status as JSON |
curl -s 'https://markdown.new/crawl/status/<jobId>?format=json' |
references/crawl.md |
| Open the hosted editor |
https://markdown.new/markdown-editor |
references/editor.md |
Reading Guide
| If the user says... |
Read |
| "Use markdown.new on this URL" |
references/url-conversion.md |
| "Turn this PDF / CSV / raw file URL into Markdown" |
references/file-conversion.md |
| "Crawl this docs section into one Markdown export" |
references/crawl.md |
| "What does the markdown.new UI/editor support?" |
references/editor.md |
| "Why did markdown.new return junk / 500 / no tokens?" |
references/gotchas.md |
Verified Behaviors
- Bare domains are normalized.
https://markdown.new/example.com?format=json resolved to https://example.com in testing.
GET /<url> defaults to text/markdown, while GET /<url>?format=json and POST / return JSON.retain_images=true changes output. Browser-mode conversion of https://www.python.org/ produced Markdown image syntax only when retain_images was true.- GitHub raw file URLs work well. GitHub
blob URLs returned HTML-heavy noise in testing.
- Crawl jobs are cached. Re-running a crawl on
https://example.com returned a cached job created on April 3, 2026.
Gotchas
- Use POST for complex target URLs: URLs with their own query strings were reliable with
POST / but a fully percent-encoded GET path returned HTTP 400 in testing.
- Do not trust
method as provenance: the service documents a native Markdown-first pipeline, but a known Markdown endpoint still reported Cloudflare Workers AI in a live test.
- Expect weak error reporting: missing
url, malformed JSON, bogus crawl IDs, and invalid paths returned 400/500 without a useful error body in testing.
- Do not assume
tokens always exists: browser-mode responses omitted tokens in testing even when the conversion succeeded.
- Crawl limits are documented inconsistently: the homepage says 100 pages in one section, while the crawl page says 500 pages and accepts
limit values up to 500.
Helper Script
Use scripts/probe_markdown_new.py when you want a structured probe instead of hand-writing curl commands. It wraps the main GET, POST, crawl, status, and upload flows and prints JSON with the HTTP status, selected headers, and parsed body.
1---2name: markdown-new3description: Use markdown.new for Cloudflare Markdown for Agents, URL/file/PDF-to-Markdown, crawl-to-Markdown, the markdown.new API, or hosted editor workflows. Do NOT use for generic scraping/search or local Markdown editing that does not need markdown.new.4---56# markdown.new78Use markdown.new to turn public URLs or files into Markdown, crawl a site section into one Markdown document, or use the hosted editor utilities.910Verified against the live service on April 9, 2026 with direct `curl` requests, browser automation, and failure-case probes.1112## Decision Tree1314What are you trying to do?1516- Convert one public page or API response into Markdown17 - Read `references/url-conversion.md`1819- Convert a remote file URL or upload a local file20 - Read `references/file-conversion.md`2122- Crawl multiple same-site pages and fetch one combined Markdown result23 - Read `references/crawl.md`2425- Use the hosted UI pages or the live editor26 - Read `references/editor.md`2728- Debug odd behavior, rate limits, query-string edge cases, or bad responses29 - Read `references/gotchas.md`3031## Quick Reference3233| Task | Command or Route | Read |34| --- | --- | --- |35| Convert one page to Markdown | `curl -s 'https://markdown.new/https://example.com'` | `references/url-conversion.md` |36| Convert one page to JSON | `curl -s 'https://markdown.new/https://example.com?format=json'` | `references/url-conversion.md` |37| Force browser rendering | `curl -s -X POST 'https://markdown.new/' -H 'Content-Type: application/json' -d '{"url":"https://example.com","method":"browser"}'` | `references/url-conversion.md` |38| Convert a remote file URL | `curl -s 'https://markdown.new/https://raw.githubusercontent.com/github/gitignore/main/README.md?format=json'` | `references/file-conversion.md` |39| Upload a local file | `curl -s -X POST 'https://markdown.new/convert' -F 'file=@notes.pdf'` | `references/file-conversion.md` |40| Start a crawl job | `curl -s -X POST 'https://markdown.new/crawl' -H 'Content-Type: application/json' -d '{"url":"https://docs.example.com","limit":50}'` | `references/crawl.md` |41| Poll crawl status as JSON | `curl -s 'https://markdown.new/crawl/status/<jobId>?format=json'` | `references/crawl.md` |42| Open the hosted editor | `https://markdown.new/markdown-editor` | `references/editor.md` |4344## Reading Guide4546| If the user says... | Read |47| --- | --- |48| "Use markdown.new on this URL" | `references/url-conversion.md` |49| "Turn this PDF / CSV / raw file URL into Markdown" | `references/file-conversion.md` |50| "Crawl this docs section into one Markdown export" | `references/crawl.md` |51| "What does the markdown.new UI/editor support?" | `references/editor.md` |52| "Why did markdown.new return junk / 500 / no tokens?" | `references/gotchas.md` |5354## Verified Behaviors55561. Bare domains are normalized. `https://markdown.new/example.com?format=json` resolved to `https://example.com` in testing.572. `GET /<url>` defaults to `text/markdown`, while `GET /<url>?format=json` and `POST /` return JSON.583. `retain_images=true` changes output. Browser-mode conversion of `https://www.python.org/` produced Markdown image syntax only when `retain_images` was true.594. GitHub raw file URLs work well. GitHub `blob` URLs returned HTML-heavy noise in testing.605. Crawl jobs are cached. Re-running a crawl on `https://example.com` returned a cached job created on April 3, 2026.6162## Gotchas63641. **Use POST for complex target URLs**: URLs with their own query strings were reliable with `POST /` but a fully percent-encoded GET path returned HTTP 400 in testing.652. **Do not trust `method` as provenance**: the service documents a native Markdown-first pipeline, but a known Markdown endpoint still reported `Cloudflare Workers AI` in a live test.663. **Expect weak error reporting**: missing `url`, malformed JSON, bogus crawl IDs, and invalid paths returned 400/500 without a useful error body in testing.674. **Do not assume `tokens` always exists**: browser-mode responses omitted `tokens` in testing even when the conversion succeeded.685. **Crawl limits are documented inconsistently**: the homepage says 100 pages in one section, while the crawl page says 500 pages and accepts `limit` values up to 500.6970## Helper Script7172Use `scripts/probe_markdown_new.py` when you want a structured probe instead of hand-writing `curl` commands. It wraps the main GET, POST, crawl, status, and upload flows and prints JSON with the HTTP status, selected headers, and parsed body.
jpcaparas