# Markdown Dot New

> Use markdown.new to fetch web content, convert files, and crawl sites as clean Markdown instead of raw HTML. Trigger this skill whenever you need to read a webpage, fetch URL content, convert a document (PDF, DOCX, XLSX, images, etc.), or crawl a website. This includes any task involving summarizing web pages, extracting content from URLs, ingesting documents, researching topics online, or gathering information from websites. If you're about to fetch HTML from a URL, use markdown.new instead — it returns clean Markdown with 80% fewer tokens.

- Skill: `frontboat/markdown-dot-new` (Agent Skill)
- Install (CLI): `npx skillmds@latest add frontboat/markdown-dot-new`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frontboat/markdown-dot-new/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: frontboat (https://skillmd.com/u/frontboat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frontboat/markdown-dot-new

---


# markdown.new — Markdown for Agents

Use markdown.new instead of raw HTML when reading web content, converting files, or crawling sites. It returns clean, structured Markdown with 80% fewer tokens — no parsing required.

**Preserve original content.** When a user asks to "get" or "fetch" content from a URL, return the actual source material directly. Do not summarize, paraphrase, or rewrite it. Only transform the content if the user explicitly requests a summary or rewrite.

**Rate limit:** 500 requests per day per IP. Monitor the `x-rate-limit-remaining` response header.

## 1. URL → Markdown

Convert any public URL to Markdown. This is the default method for reading web pages.

**Simple GET** — prepend `https://markdown.new/` to the target URL:

```bash
curl -s 'https://markdown.new/https://example.com'
```

**POST with options:**

```bash
curl -s 'https://markdown.new/' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "method": "auto", "retain_images": false}'
```

**Options:**

| Parameter       | Values                  | Default | When to use                                |
| --------------- | ----------------------- | ------- | ------------------------------------------ |
| `method`        | `auto`, `ai`, `browser` | `auto`  | Use `browser` for JavaScript-heavy SPAs    |
| `retain_images` | `true`, `false`         | `false` | Set `true` when images are relevant to the task |

Options also work as query parameters: `https://markdown.new/https://example.com?method=browser&retain_images=true`

The response is returned as `text/markdown` with an `x-markdown-tokens` header indicating the estimated token count.

## 2. File → Markdown

Convert documents to Markdown. Supports 20+ formats including PDF, DOCX, XLSX, XLS, ODS, ODT, CSV, JSON, XML, HTML, TXT, JPG, PNG, WebP, and SVG. Maximum file size is 10 MB.

**Remote file (by URL):**

```bash
curl -s 'https://markdown.new/https://example.com/report.pdf'
```

Or via POST:

```bash
curl -s 'https://markdown.new/' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/report.pdf"}'
```

**Local file upload:**

```bash
curl -s 'https://markdown.new/convert' \
  -F 'file=@document.pdf'
```

POST responses return JSON with metadata:

```json
{
  "success": true,
  "url": "https://example.com/report.pdf",
  "title": "Report Title",
  "content": "# Report Title\n\n...",
  "tokens": 850
}
```

Upload responses nest data under a `data` key with `filename` and `file_type` fields.

## 3. Crawl → Markdown

Crawl an entire website section and retrieve all pages as Markdown. This is an async, job-based process: start a crawl, then poll for results.

**Start a crawl:**

```bash
curl -X POST 'https://markdown.new/crawl' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://docs.example.com", "limit": 50}'
```

Returns a job ID.

**Check status and download results:**

```bash
# All pages concatenated as Markdown
curl -s 'https://markdown.new/crawl/status/{jobId}'

# Per-page records as JSON
curl -s 'https://markdown.new/crawl/status/{jobId}?format=json'
```

**Crawl options:**

| Parameter         | Description                               | Default |
| ----------------- | ----------------------------------------- | ------- |
| `url`             | Starting URL (required)                   | —       |
| `limit`           | Maximum pages to crawl, 1–500             | 500     |
| `depth`           | Maximum link depth, 1–10                  | 5       |
| `render`          | Enable JavaScript rendering for SPAs      | false   |
| `source`          | URL discovery: `all`, `sitemaps`, `links` | `all`   |
| `maxAge`          | Maximum cache age in seconds, 0–604800    | 86400   |
| `includePatterns` | Only visit URLs matching these wildcards  | auto    |
| `excludePatterns` | Skip URLs matching these wildcards        | —       |

Results are stored for 14 days. Each crawl consumes 50 request units (approximately 10 crawls per day).

To cancel a crawl: `DELETE /crawl/status/{jobId}`

## Quick Reference

| Task                                               | Method                                      |
| -------------------------------------------------- | ------------------------------------------- |
| Read a single web page                             | URL → Markdown (GET)                        |
| Fetch a remote PDF, DOCX, or spreadsheet           | File → Markdown (GET or POST with URL)      |
| Convert a local file on disk                       | File → Markdown (POST /convert with upload) |
| Retrieve content from multiple pages on a site     | Crawl → Markdown                            |
| Handle a JS-heavy SPA that returns blank content   | URL → Markdown with `method=browser`        |

## Key Behaviors

- **Start with the simple GET.** `https://markdown.new/<url>` auto-selects the best conversion method and handles most cases.
- **Fall back to browser rendering.** If a page returns empty or incomplete content, retry with `method=browser`.
- **Poll crawl jobs.** Crawling is asynchronous — poll the status endpoint every few seconds until the job completes.
- **Use multiple crawl entry points.** Sites often organize content under different URL prefixes. If the first crawl only captures one section, start additional crawls from other entry points (e.g., `/reference/`, `/extensions/`) for full coverage.
- **Leave images off by default.** Only set `retain_images=true` when the task specifically requires image content.
- **Public URLs only.** Paywalled or authenticated pages are not supported.
- **Return raw output.** Save and present the markdown.new response directly. Do not rewrite, paraphrase, or summarize unless the user explicitly requests it.