---
name: markdown-page
description: Publish Markdown as a permanent public URL when a user asks to share, host, or create a link for Markdown content.
---

# markdown.page

Publish Markdown to a permanent public URL without an account or API key.

## When to use this skill

Use this skill when the user asks to:

- publish or host Markdown
- turn a report, guide, changelog, notes, or other long-form content into a link
- create a public URL that another person or tool can fetch

Do not use it for private or sensitive content, secrets, credentials, personal data, raw HTML, CSS, JavaScript, or content that will need to be edited later.

## Safety requirements

Every published page is public and immutable. Before publishing, make sure the user intends the content to be public. Never publish credentials, private keys, access tokens, private personal information, or content the user has not agreed to share.

If the content needs a correction after publication, publish a new page and return the new URL.

## Publish Markdown

Send the completed Markdown as the request body:

```http
POST https://markdown.page/api/publish
Content-Type: text/markdown
Accept: application/json
```

Example:

```bash
curl https://markdown.page/api/publish \
  -H 'Content-Type: text/markdown' \
  -H 'Accept: application/json' \
  --data-binary @document.md
```

A successful response has HTTP status `201`:

```json
{
  "slug": "JCLcR63O",
  "url": "https://markdown.page/JCLcR63O",
  "raw_url": "https://markdown.page/JCLcR63O.md"
}
```

Return `url` to the user. Use `raw_url` when an agent or tool needs the original Markdown.

## Read a page

```http
GET https://markdown.page/{slug}
GET https://markdown.page/{slug}.md
```

The first URL negotiates HTML, plaintext, or Markdown using `Accept`. The `.md` URL always returns the original Markdown.

## Errors

- `400`: malformed or empty request
- `413`: Markdown exceeds the 1 MB page limit
- `415`: unsupported content type
- `429`: rate limited; back off before retrying and do not loop

The maximum Markdown page size is 1 MB and the maximum request envelope is 2 MB.

## MCP alternative

Agents with MCP support may call `publish_markdown({ markdown: string })` over HTTP JSON-RPC at:

```
POST https://markdown.page/mcp
```

MCP authentication is not required and SSE streaming is not supported.

## Further documentation

- Agent discovery: https://markdown.page/llms.txt
- API documentation: https://markdown.page/api.md
- OpenAPI: https://markdown.page/openapi.json
- FAQ: https://markdown.page/faq.md