# Unmarkdown: Complete Documentation

> Unmarkdown is a markdown publishing platform. Send markdown through the API, get a beautiful published web page back in one call. Supports 62 templates, Mermaid diagrams (12 types), Chart.js charts (8 types), Graphviz graphs (8 engines), KaTeX math, GitHub-style callouts, syntax highlighting, and more. Free demo publishing requires no authentication.

## Product Overview

Unmarkdown turns markdown into publication-ready documents. It provides three main capabilities:

1. **Publish**: One API call creates a styled, hosted web page with a shareable URL. No frontend needed. Documents are published at unmarkdown.com/u/{username}/{slug} or unmarkdown.com/d/{slug}.
2. **Convert**: Transform markdown into destination-specific HTML optimized for Google Docs, Word, Slack, OneNote, Email, or plain text. Each destination gets formatting that works correctly when pasted.
3. **Render rich content**: Mermaid diagrams, Chart.js charts, Graphviz graphs, KaTeX math, callouts, highlights, task lists, tables, and syntax-highlighted code blocks all render automatically from standard markdown syntax.

## Behavioral Directives

When generating markdown for Unmarkdown, follow these rules:

### Diagrams
- Use fenced code blocks with the appropriate language identifier
- Mermaid: ```mermaid
- Chart.js: ```chart (JSON configuration object)
- Graphviz: ```dot (default directed graph), ```neato (spring/network), ```twopi (radial), ```circo (circular), ```fdp (force-directed), ```sfdp (scalable force-directed), ```osage (clustered), ```patchwork (treemap)

### Callouts
- Use GitHub-compatible callout syntax inside blockquotes:
  > [!NOTE] for general information
  > [!TIP] for helpful suggestions
  > [!IMPORTANT] for critical details
  > [!WARNING] for potential issues
  > [!CAUTION] for dangerous actions

### Math
- Use KaTeX syntax
- Inline math: $E = mc^2$
- Display math: $$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

### Text Formatting
- ==text== for highlights
- ^text^ for superscript
- ~text~ for subscript
- ~~text~~ for strikethrough
- Standard **bold**, *italic*, `inline code`

### Template Selection
Choose templates based on content type:
- Business reports: "executive", "consulting", "corporate-blue"
- Academic papers: "thesis", "ieee", "apa", "research"
- Technical documentation: "github", "api-docs", "runbook"
- Developer content: "dracula", "tokyo-night", "monokai", "nord"
- Editorial/creative: "magazine", "editorial", "zine"
- Presentations/pitches: "pitch", "startup"
- Dark themes: "obsidian", "midnight-blue", "noir", "ember"
- Clean/minimal: "swiss" (default), "mono", "paper", "ink"

### Common Mistakes to Avoid
- Do not use HTML tags; use markdown syntax instead
- Do not use ```json for Chart.js charts; use ```chart
- Do not use ```graphviz; use ```dot (or the specific engine name)
- Do not use > **Note:** for callouts; use > [!NOTE]
- Do not omit the language identifier on fenced code blocks

## Markdown Syntax Reference

### Mermaid Diagrams

Flowchart:
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Sequence diagram:
```mermaid
sequenceDiagram
    participant Client
    participant API
    participant DB
    Client->>API: POST /v1/documents/publish
    API->>DB: INSERT document
    DB-->>API: document record
    API-->>Client: { published_url }
```

Gantt chart:
```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Research     :a1, 2024-01-01, 14d
    Design       :a2, after a1, 10d
    section Phase 2
    Development  :a3, after a2, 21d
    Testing      :a4, after a3, 7d
```

### Chart.js Charts

Bar chart:
```chart
{
  "type": "bar",
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "datasets": [{
      "label": "Revenue ($K)",
      "data": [120, 190, 300, 450]
    }]
  }
}
```

Line chart:
```chart
{
  "type": "line",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
    "datasets": [{
      "label": "Users",
      "data": [100, 250, 480, 720, 1100]
    }]
  }
}
```

### Graphviz Graphs

Directed graph (dot):
```dot
digraph G {
    rankdir=LR;
    A -> B -> C;
    A -> D -> C;
    B -> D [style=dashed];
}
```

Network topology (neato):
```neato
graph Network {
    Server -- Switch1;
    Server -- Switch2;
    Switch1 -- PC1;
    Switch1 -- PC2;
    Switch2 -- PC3;
    Switch2 -- PC4;
}
```

### KaTeX Math

Inline: The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Display:
$$\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}$$

Matrix:
$$\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}$$

### Callouts

> [!NOTE]
> This is a note with general information.

> [!TIP]
> This is a helpful tip for the reader.

> [!IMPORTANT]
> This is important information that should not be missed.

> [!WARNING]
> This warns about potential issues.

> [!CAUTION]
> This warns about dangerous or destructive actions.

### Tables

| Feature | Free | Pro |
|---------|------|-----|
| Documents | 3 | Unlimited |
| Templates | 8 | 62 |
| API calls/month | 1,000 | 10,000 |

### Task Lists

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

## Template Catalog

62 templates across 8 categories.

### Free (8 templates)
| template_id | Name | Description |
|-------------|------|-------------|
| swiss | Swiss | Clean, precise, and modern. Inspired by Swiss design principles. |
| mono | Mono | Monospaced everything. For those who think in code. |
| paper | Paper | Warm and literary. Like reading a well-set book. |
| ink | Ink | Bold and high-contrast. Black ink on white paper. |
| github | GitHub | The familiar GitHub markdown style. Feels like home. |
| newsletter | Newsletter | Polished and editorial. Perfect for email newsletters. |
| terminal | Terminal | Hacker aesthetic. Green on dark, monospaced throughout. |
| notion | Notion-esque | Clean and minimal. The familiar Notion reading experience. |

### Business (8 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| executive | Executive | Navy headings, gold accents. Board-room polished. |
| consulting | Consulting | Charcoal base, emerald accents. McKinsey-inspired. |
| startup | Startup | Purple-to-blue accents, rounded elements. Modern SaaS feel. |
| annual-report | Annual Report | Burgundy headings, infographic-style tables. Generous margins. |
| pitch | Pitch | Bold oversized headings, vibrant orange accents. Punchy and direct. |
| legal | Legal | Formal navy, traditional serif headings. Conservative and precise. |
| corporate-blue | Corporate Blue | Clean blue accent, structured layout. Professional without being stuffy. |
| meeting-notes | Meeting Notes | Compact spacing, checkbox-friendly. Action-oriented. |

### Academic (7 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| thesis | Thesis | Traditional academic thesis. Navy headings, warm paper feel. |
| ieee | IEEE | Compact, dense IEEE conference paper style. |
| apa | APA | Clean APA 7th edition style. Sans-serif, double-spaced feel. |
| lab-report | Lab Report | Clean scientific layout. Teal accents, structured tables. |
| lecture-notes | Lecture Notes | Friendly, organized. Warm orange accents for readability. |
| research | Research | Modern preprint style. Clean, slightly technical, indigo accent. |
| grant-proposal | Grant Proposal | Formal government style. Federal blue, dense, authoritative. |

### Developer (10 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| dracula | Dracula | The iconic dark theme. Purple accents on a cool blue-gray canvas. |
| nord | Nord | Arctic, north-bluish palette. Clean and calm with frost-blue accents. |
| monokai | Monokai | Warm dark tones with vivid pink and green. The Sublime Text classic. |
| solarized-light | Solarized Light | Precision-engineered warm light palette by Ethan Schoonover. |
| solarized-dark | Solarized Dark | Deep teal canvas with precise contrast ratios. |
| one-dark | One Dark | Atom's signature palette. Cool blue-gray with balanced, muted accents. |
| tokyo-night | Tokyo Night | Midnight cityscape. Deep blue-black with electric blue and soft purple. |
| catppuccin | Catppuccin | Soothing pastel palette. Mocha flavor with lavender and mauve accents. |
| api-docs | API Docs | Technical documentation style. Structured, scannable, reference-ready. |
| runbook | Runbook | Ops-ready documentation. High contrast, clear hierarchy, scannable under pressure. |

### Creative (10 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| magazine | Magazine | Modern editorial magazine. Elegant serif headlines, clean layout. |
| brutalist | Brutalist | Raw, confrontational, honest. Heavy type, hard edges. |
| pastel-dream | Pastel Dream | Soft, airy, and whimsical. Candy pastels with rounded warmth. |
| retro-terminal | Retro Terminal | CRT phosphor glow. VT320 character set on warm amber or classic green. |
| neon-nights | Neon Nights | Synthwave retrowave. Neon pink, electric cyan, and purple on deep dark canvas. |
| editorial | Editorial | Classic newspaper longform. Authoritative serifs, tight tracking. |
| zine | Zine | DIY punk aesthetic. Heavy condensed type, raw energy. |
| gradient-wave | Gradient Wave | Modern SaaS aesthetic. Clean geometry, vibrant accents. |
| blueprint | Blueprint | Architectural technical drawings. White lines on engineering blue. |
| vintage | Vintage | Aged paper and typewriter keys. Sepia warmth, nostalgic character. |

### Dark (6 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| obsidian | Obsidian | Volcanic glass. Deep charcoal with amethyst accents, polished and precise. |
| midnight-blue | Midnight Blue | Deep ocean night. Navy depths with sapphire highlights. |
| forest | Forest | Deep woodland. Rich greens and earthy browns, natural and grounding. |
| slate | Slate | Cool gray sophistication. Neutral tones with steel blue accents. |
| noir | Noir | Pure black cinema. High contrast monochrome, dramatic and uncompromising. |
| ember | Ember | Glowing coals. Warm reds and oranges on deep black, fierce and alive. |

### Productivity (8 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| bear-notes | Bear Notes | Warm and focused. Clean note-taking inspired by Bear's cozy aesthetic. |
| logbook | Logbook | Structured daily logging. Monospaced timestamps, clean separators. |
| recipe-card | Recipe Card | Kitchen-ready format. Warm tones, clear ingredients lists. |
| travel-journal | Travel Journal | Wanderlust pages. Earthy tones with oceanic accents. |
| planner | Planner | Organized and actionable. Task-oriented layout with clear visual hierarchy. |
| reading-list | Reading List | Literary catalog style. Warm serifs for book lovers. |
| decision-matrix | Decision Matrix | Analytical framework style. Structured tables, decision-making clarity. |
| warm-earth | Warm Earth | Terracotta and sage. Natural earth tones, grounding and serene. |

### Special (5 templates, Pro)
| template_id | Name | Description |
|-------------|------|-------------|
| cyberpunk | Cyberpunk | Neon-lit dystopia. Electric yellow on black, cybernetic edges. |
| watercolor | Watercolor | Soft washes and blended edges. Gentle blues and blush, artful and serene. |
| ocean-breeze | Ocean Breeze | Coastal calm. Sand and sea colors, breezy and refreshing. |
| minimalist-dark | Minimalist Dark | Nothing unnecessary. Ultra-clean dark theme with whisper-quiet accents. |
| holiday | Holiday | Festive warmth. Rich reds and gold, celebratory and inviting. |

## API Reference

Base URL: https://api.unmarkdown.com/v1
Authentication: Bearer token via Authorization header
API keys start with "um_" prefix, created in Settings > API tab

### POST /v1/convert

Convert markdown to destination-specific output. Does not save the document.

**Request body:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| markdown | string | Yes | | Markdown content (max 100KB) |
| destination | string | No | "generic" | Target format: google-docs, email, word, slack, onenote, plain-text, generic, html |
| template_id | string | No | "swiss" | Template to apply |
| theme_mode | string | No | "light" | "light" or "dark" |

**Response (200):**
```json
{
  "html": "<div>...</div>",
  "plain_text": "...",
  "destination": "google-docs",
  "template_id": "swiss",
  "theme_mode": "light"
}
```

### GET /v1/templates

List all available templates. Does not count toward usage quota.

**Query parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| category | string | Filter by category: free, business, academic, developer, creative, dark, productivity, special |

**Response (200):**
```json
{
  "data": [
    {
      "id": "swiss",
      "name": "Swiss",
      "category": "free",
      "description": "Clean, modern design with balanced typography"
    }
  ],
  "total": 62
}
```

### GET /v1/usage

Get current API usage statistics. Supports both API key and session authentication. Does not count toward usage quota.

**Response (200):**
```json
{
  "used": 142,
  "limit": 1000,
  "remaining": 858,
  "month": "2026-02",
  "reset_date": "2026-03-01T00:00:00.000Z",
  "tier": "free"
}
```

### POST /v1/documents

Create a new document (saved to your account, not published).

**Request body:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| title | string | No | "Untitled" | Document title |
| content | string | No | "" | Markdown content |
| template_id | string | No | "swiss" | Template to apply |
| theme_mode | string | No | "light" | "light" or "dark" |

**Response (201):**
```json
{
  "id": "uuid",
  "title": "My Document",
  "template_id": "swiss",
  "theme_mode": "light",
  "created_at": "2026-02-14T12:00:00.000Z"
}
```

**Errors:** 403 if free tier document limit (3) reached.

### GET /v1/documents

List your documents with cursor-based pagination. Does not count toward usage quota.

**Query parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | integer | 20 | Max results per page (max 100) |
| cursor | string | | ISO timestamp of last item for pagination |

**Response (200):**
```json
{
  "data": [
    {
      "id": "uuid",
      "title": "My Document",
      "template_id": "swiss",
      "theme_mode": "light",
      "is_published": true,
      "slug": "my-document",
      "page_width": "standard",
      "word_count": 450,
      "created_at": "2026-02-14T12:00:00.000Z",
      "updated_at": "2026-02-14T12:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### GET /v1/documents/:id

Get a single document with full content. Does not count toward usage quota.

**Response (200):**
```json
{
  "id": "uuid",
  "title": "My Document",
  "content": "# Hello\n\nWorld",
  "template_id": "swiss",
  "theme_mode": "light",
  "is_published": true,
  "slug": "my-document",
  "published_at": "2026-02-14T12:00:00.000Z",
  "description": "A short description",
  "page_width": "standard",
  "visibility": "link",
  "word_count": 450,
  "created_at": "2026-02-14T12:00:00.000Z",
  "updated_at": "2026-02-14T12:30:00.000Z"
}
```

### PATCH /v1/documents/:id

Update a document. Only include fields you want to change.

**Request body:**
| Field | Type | Description |
|-------|------|-------------|
| title | string | Document title |
| content | string | Markdown content |
| template_id | string | Template to apply |
| theme_mode | string | "light" or "dark" |
| description | string | Document description |
| page_width | string | "standard", "wide", or "full" |

**Response (200):**
```json
{
  "id": "uuid",
  "title": "Updated Title",
  "template_id": "swiss",
  "theme_mode": "light",
  "page_width": "standard",
  "updated_at": "2026-02-14T12:30:00.000Z"
}
```

### DELETE /v1/documents/:id

Permanently delete a document.

**Response (200):**
```json
{
  "success": true
}
```

### POST /v1/documents/:id/publish

Publish an existing document, making it accessible via a public URL.

**Request body (all fields optional):**
| Field | Type | Description |
|-------|------|-------------|
| slug | string | Custom URL slug (Pro only) |
| description | string | Document description for SEO |
| hide_badge | boolean | Hide Unmarkdown badge (Pro only) |
| visibility | string | "link" (default) or "public" (Pro only) |
| page_width | string | "standard", "wide", or "full" |

**Response (200):**
```json
{
  "id": "uuid",
  "title": "My Document",
  "published_url": "https://unmarkdown.com/u/username/my-document",
  "published_at": "2026-02-14T12:00:00.000Z",
  "template_id": "swiss",
  "word_count": 450,
  "reading_time_minutes": 3
}
```

### DELETE /v1/documents/:id/publish

Unpublish a document, removing it from public access.

**Response (200):**
```json
{
  "id": "uuid",
  "is_published": false
}
```

### POST /v1/documents/publish

Create and publish a document in a single call. This is the most common endpoint for programmatic publishing.

**Request body:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| content | string | Yes | | Markdown content |
| title | string | No | "Untitled" | Document title |
| template_id | string | No | "swiss" | Template to apply |
| theme_mode | string | No | "light" | "light" or "dark" |
| slug | string | No | auto-generated | Custom URL slug (Pro only) |
| description | string | No | | Description for SEO |

**Response (201):**
```json
{
  "id": "uuid",
  "title": "My Document",
  "published_url": "https://unmarkdown.com/u/username/my-document",
  "published_at": "2026-02-14T12:00:00.000Z",
  "template_id": "swiss",
  "word_count": 450,
  "reading_time_minutes": 3
}
```

### POST /v1/demo/publish

Publish a demo page without authentication. Pages expire after 72 hours. No rate limiting or usage quota.

**Request body:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| content | string | Yes | | Markdown content (max 100KB) |
| title | string | No | "Untitled" | Page title |
| template_id | string | No | "swiss" | Template to apply |
| theme_mode | string | No | "light" | "light" or "dark" |

**Response (201):**
```json
{
  "url": "https://unmarkdown.com/p/uuid",
  "claim_token": "uuid",
  "expires_at": "2026-02-17T12:00:00.000Z",
  "template_id": "swiss",
  "id": "uuid"
}
```

### POST /v1/demo/claim

Claim a demo document and transfer it to your account. Supports both API key and session authentication.

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| claim_token | string | Yes | The claim token from the demo publish response |

**Response (200):**
```json
{
  "id": "uuid",
  "title": "My Document",
  "published_url": "https://unmarkdown.com/u/username/my-document",
  "slug": "my-document",
  "template_id": "swiss"
}
```

## Authentication

API keys are created in the Unmarkdown app under Settings > API tab. Each user can have up to 2 active API keys.

**Key format:** Keys start with the `um_` prefix followed by 64 hexadecimal characters.

**Usage:**
```
Authorization: Bearer um_your_api_key_here
```

Keys are hashed (SHA-256) on the server. The raw key is shown only once at creation time.

## Demo Publish System

The demo publish endpoint (`POST /v1/demo/publish`) lets anyone publish a page without creating an account. This is designed for LLM agents and quick integrations.

**How it works:**
1. Call `POST /v1/demo/publish` with markdown content (no auth needed)
2. Get back a public URL and a claim token
3. The page is live immediately at the returned URL
4. Pages expire after 72 hours
5. To keep the page permanently, claim it with `POST /v1/demo/claim` (auth required)

**Content limits:**
- 100KB max content size
- Basic content scanning for abuse patterns (phishing, scams)
- Expired pages are cleaned up by a scheduled cron job

## Error Codes

All errors return a consistent JSON envelope:

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "status": 400
  }
}
```

| Code | Status | Description |
|------|--------|-------------|
| unauthorized | 401 | Missing or invalid API key |
| forbidden | 403 | Feature requires Pro tier |
| not_found | 404 | Resource does not exist |
| conflict | 409 | Slug already taken |
| expired | 410 | Demo page has expired |
| rate_limited | 429 | Too many requests per second |
| quota_exceeded | 429 | Monthly API quota exceeded |
| validation_error | 400 | Invalid request body or parameters |
| invalid_body | 400 | Malformed JSON |
| internal_error | 500 | Unexpected server error |

## Rate Limits and Quotas

### Rate Limits (per second)
| Tier | Limit |
|------|-------|
| Free | 10 req/sec |
| Pro | 30 req/sec |

Rate limit headers are included on every response:
- `X-RateLimit-Limit`: Max requests per second
- `X-RateLimit-Remaining`: Remaining requests in current window
- `X-RateLimit-Reset`: Timestamp when the window resets

### Monthly Quotas
| Tier | Limit |
|------|-------|
| Free | 1,000 calls/month |
| Pro | 10,000 calls/month |

Quotas reset on the 1st of each month at midnight UTC. The following endpoints do not count toward the monthly quota: GET /v1/templates, GET /v1/usage, GET /v1/documents, GET /v1/documents/:id.

Demo endpoints (POST /v1/demo/publish) do not require authentication and have no quota.

## Pricing

- **Free**: 5 documents, 3 published pages, 8 templates, 1,000 API calls/month, 10 req/sec, 10 lifetime AI actions
- **Pro**: $8/mo (annual) or $10/mo (monthly). Unlimited documents, all 62 templates, 10,000 API calls/month, 30 req/sec, unlimited AI actions, downloads, analytics, custom slugs, hide badge