SKILL.md
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
- Read references/crawl.md
- 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 '[email protected]' |
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=jsonresolved tohttps://example.comin testing. GET /<url>defaults totext/markdown, whileGET /<url>?format=jsonandPOST /return JSON.retainimages=truechanges output. Browser-mode conversion ofhttps://www.python.org/produced Markdown image syntax only whenretainimageswas true.- GitHub raw file URLs work well. GitHub
blobURLs returned HTML-heavy noise in testing. - Crawl jobs are cached. Re-running a crawl on
https://example.comreturned 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
methodas provenance: the service documents a native Markdown-first pipeline, but a known Markdown endpoint still reportedCloudflare Workers AIin 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
tokensalways exists: browser-mode responses omittedtokensin 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
limitvalues up to 500.
Helper Script
Use scripts/probemarkdownnew.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.