# mdland docs

mdland is a public markdown sharing service. Upload markdown, get a URL. No account needed.

## Display parameters

You can customize how a shared document looks by adding query parameters to the URL. This lets you control fonts, colors, width, and more, without changing the original document.

| Param | Values | Description |
|-------|--------|-------------|
| `f` | `mono`, `sans`, `serif` | Font family. `mono` for monospaced, `sans` for system sans-serif (default), `serif` for serif. |
| `w` | `full`, `compact`, `narrow` | Content width. `full` stretches to 100%, `compact` is the default 860px, `narrow` is 640px. |
| `bg` | hex color (no #) | Background color override. Example: `bg=1a1a2e` |
| `fg` | hex color (no #) | Text color override. Example: `fg=e0e0e0` |
| `link` | hex color (no #) | Link color override. Example: `link=ff6b6b` |
| `size` | `10` to `32` | Base font size in pixels. Default is 16. |
| `lh` | `1.0` to `3.0` | Line height. Default is 1.6. |
| `theme` | `light`, `dark` | Force a specific theme. Disables the user's theme toggle. |
| `chrome` | `none` | Hide the header and footer. Useful for embedding or clean presentation. |

### Examples

Monospaced font, dark theme, full width:

```
mdland.cc/d/abc123?f=mono&theme=dark&w=full
```

Custom colors, narrow reading width, larger text:

```
mdland.cc/d/abc123?bg=fdf6e3&fg=657b83&link=268bd2&w=narrow&size=18
```

Clean embed with no header/footer:

```
mdland.cc/d/abc123?chrome=none&theme=light
```

Tight line spacing for code-heavy docs:

```
mdland.cc/d/abc123?f=mono&lh=1.3&size=14
```

## PIN protection

Documents can be protected with a 4-character PIN. When set, visitors must enter the PIN before viewing the content.

- Set the PIN when uploading (via API or GoTools share sheet)
- The PIN is also required to delete the document
- You can bypass the form by adding `?pin=xxxx` to the URL

## API

### Upload a document

```
POST /api/v1/documents
Content-Type: application/json

{
  "content": "# Hello\n\nYour markdown here.",
  "filename": "readme.md",
  "title": "Hello",
  "pin": "1234"
}

Response 201:
{
  "hash": "a7x9k2m4np",
  "url": "https://mdland.cc/d/a7x9k2m4np",
  "delete_url": "https://mdland.cc/d/a7x9k2m4np/delete?token=...",
  "title": "Hello",
  "has_pin": true
}
```

### Update a document

```
POST /api/v1/documents/:hash
Content-Type: application/json

{
  "content": "# Updated\n\nNew content."
}
```

### Delete a document

```
DELETE /api/v1/documents/:hash?token=your-delete-token
```

### Create a folder

```
POST /api/v1/folders
Content-Type: application/json

{
  "name": "Project Docs"
}

Response 201:
{
  "hash": "b3y8j1q5wr",
  "url": "https://mdland.cc/f/b3y8j1q5wr",
  "name": "Project Docs"
}
```

### Add document to folder

```
POST /api/v1/folders/:hash/documents
Content-Type: application/json

{
  "content": "# Setup Guide\n\n...",
  "filename": "setup.md"
}
```

### Raw markdown

```
GET /raw/:hash
```

Returns the raw markdown content as `text/plain`.

### Authentication

Optional. Pass an API key via the `Authorization` header:

```
Authorization: Bearer your-api-key
```

Uploads work without a key. Keys are used for provenance tracking and future features like listing your uploads or deletion by key.

## View URLs

| Path | Description |
|------|-------------|
| `/d/:hash` | View rendered document |
| `/f/:hash` | View folder listing |
| `/raw/:hash` | Raw markdown text |
| `/upload` | Upload page (drag-drop, paste) |
| `/docs` | This documentation |