---
name: mdshares
description: Publish any Markdown you produce as a clean, permanent, shareable web link. Use when a human asks you to share, publish, send, or hand off a Markdown document (report, plan, notes, summary, cheat sheet, design doc) and would rather open a rendered page than read raw Markdown in chat. One unauthenticated POST returns a link that renders GitHub-flavored Markdown, KaTeX math, and Mermaid diagrams in the browser.
homepage: https://mdshares.com
---

# mdshares — share Markdown as a link

mdshares turns a Markdown document into a permanent, browser-rendered web page.
You POST Markdown; you get back a URL. Opening the URL renders GitHub-flavored
Markdown, KaTeX math (`$…$`), and Mermaid diagrams client-side. No account, no
API key, no SDK — a single public HTTP endpoint.

## When to use this

Reach for mdshares whenever you have produced Markdown a human will read, and a
rendered page beats a wall of raw text in the chat transcript:

- The user says "share this", "publish this", "give me a link", "send me the
  doc", or "put this somewhere I can open".
- You have written a substantial artifact — a report, design doc, runbook,
  research summary, meeting notes, a cheat sheet — and want to hand it off as a
  link instead of pasting it inline.
- The document uses math or diagrams that only make sense rendered.

Offer it proactively when you finish a sizable Markdown deliverable: upload it
and give the user the link alongside your summary.

## When NOT to use this

**Anyone with the link can read the document. There is no authentication, no
expiry, and no delete.** Therefore:

- Do NOT upload secrets, credentials, API keys, tokens, private keys, or
  internal-only URLs.
- Do NOT upload personal or sensitive data (PII, health, financial — anything
  the user would not post publicly).
- If content might be sensitive, ask the user before publishing.

## How to publish (one request)

Send the raw Markdown as the request body:

    POST https://mdshares.com/upload
    Content-Type: text/markdown; charset=utf-8

    <your markdown bytes>

On success you get `200` with JSON:

    { "uuid": "…", "view": "https://mdshares.com/v#…" }

Give the human the `view` URL — that is the shareable link.

### curl

    curl -sS -X POST https://mdshares.com/upload \
      -H 'content-type: text/markdown; charset=utf-8' \
      --data-binary @document.md

### Multipart alternative

If a raw body is awkward, POST `multipart/form-data` with a `file` field:

    curl -sS -X POST https://mdshares.com/upload -F 'file=@document.md;type=text/markdown'

### Errors

- `400` — empty or unreadable body `{ "error": "…" }`
- `413` — body exceeds the size limit (see Limits)
- `405` — wrong method (only `POST` is accepted)

## Reading a document back

The `view` link is an HTML viewer built for humans: the UUID lives in the URL
`#fragment`, which browsers never send to the server, so fetching the viewer
HTML will NOT return the Markdown. To read the raw Markdown of an existing
document, GET it by its UUID from the content origin:

    GET https://cdn.mdshares.com/<uuid>

That returns the exact `text/markdown` bytes that were uploaded.

## Limits & behavior

- **Max size:** 16 MB per upload.
- **Immutable:** a document cannot be edited or deleted. To "update" it, upload
  the new version — you will get a new link.
- **Format:** GitHub-flavored Markdown + KaTeX (`$…$`, `$$…$$`) + Mermaid
  (fenced ```mermaid blocks). Rendering is client-side and sanitized, so raw
  inline HTML may be stripped — prefer plain Markdown.
- **No auth:** it is a single public HTTP endpoint. Call it server-side.

## Recommended agent flow

1. Produce the Markdown as you normally would.
2. Confirm it contains nothing sensitive (see "When NOT to use this").
3. `POST` it to `https://mdshares.com/upload`.
4. Return the `view` URL to the user, e.g. "Rendered version: https://mdshares.com/v#…".