---
name: html-to-link-md
version: 1.0.0
description: Publish a Markdown document to HTML To Link. Anonymous agents can create and update their own 24-hour markdown pages; an account token enables long-term management.
---

# HTML To Link Markdown Skill

Use this skill to publish a Markdown file or content to a public page on `https://htmlto.link`.

## Optional env

- `HTML_TO_LINK_TOKEN`: optional. Without it, publish as a guest and get a 24-hour page. With it, use account permissions to create, update, and manage pages.

**Where to get `HTML_TO_LINK_TOKEN`:** tell the user to visit `https://htmlto.link/skill`, sign in, and copy their API token there. Then the user sets it in their shell before asking you to publish:

```bash
# macOS / Linux
export HTML_TO_LINK_TOKEN="<paste token>"

# Windows PowerShell
$env:HTML_TO_LINK_TOKEN="<paste token>"
```

When the token is not set, publish as a guest and mention that the page is temporary (~24h). Never ask for the token value in chat — the user should set it themselves.

## Workflow

1. Try to read `HTML_TO_LINK_TOKEN` from the environment.
2. Read `.htmltolink.json` from the project root. Without an account token, update a project-owned temporary markdown page only when both `shareUrl` and `updateToken` are present.
3. Read the Markdown content. If the user gives a `.md` file path, read that file. If they give raw markdown, use it directly.
4. Extract the title from the first `#` heading (or first non-empty line), trimming to a reasonable length.
5. Create a new page:

```bash
curl -X POST "https://htmlto.link/api/shares" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<full markdown content>",
    "title": "my note",
    "templateId": "plain"
  }'
```

Logged-in users add `Authorization: Bearer $HTML_TO_LINK_TOKEN`.

For an anonymous update of an existing page, use `PUT` with the slug in the path and both `updateToken` and the saved `templateId`:

```bash
curl -X PUT "https://htmlto.link/api/shares/<slug from .htmltolink.json>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<full markdown content>",
    "title": "my note",
    "templateId": "<templateId saved in .htmltolink.json>",
    "updateToken": "<updateToken from .htmltolink.json>"
  }'
```

`slug` identifies the page; `updateToken` grants update access to that temporary page. `templateId` is optional and defaults to `plain` when omitted. The API must reject missing or mismatched credentials.

## Project config file

After a successful anonymous publish, create or replace `.htmltolink.json` with this structure:

```json
{
  "shareUrl": "https://htmlto.link/s/xxxxxxxx",
  "slug": "xxxxxxxx",
  "updateToken": "updateToken returned by the API",
  "templateId": "visual template id, defaults to plain when omitted",
  "temporary": true,
  "expiresAt": "expiresAt returned by the API"
}
```

After each update, replace the corresponding fields with the latest response. This file grants update access, so add it to `.gitignore` and never commit `updateToken`.

## Template (`templateId`)

`templateId` selects the visual template for the rendered page. It is **optional** for both `POST` and `PUT`.

**How to choose:**
- If the user asks for a specific look ("card style", "minimal", "cyberpunk", "dark", "notebook", …), map their wording to the closest template below and pass its id.
- If the user does not mention any style, **omit `templateId`** — the API defaults to `plain` (a clean, simple template). Do not invent a template id.
- If you pass an invalid/unknown id, the API falls back to `plain` (never fails).

**All valid `templateId` values:**

| id | style |
|----|-------|
| `plain` | 简洁 / clean (default) |
| `memo` | 备忘录 / memo pad |
| `popart` | 波普 / pop art |
| `warm` | 温暖 / warm |
| `terminal` | 终端 / terminal |
| `notebook` | 笔记本 / notebook |
| `darktech` | 暗色科技 / dark tech |
| `cyberpunk` | 赛博朋克 / cyberpunk |
| `glassmorphism` | 毛玻璃 / glassmorphism |
| `traditionalchinese` | 国风 / traditional Chinese |
| `coilnotebook` | 线圈本 / coil notebook |
| `purpleticket` | 紫票 / purple ticket |
| `bytedance` | 字节风 / bytedance |
| `alibaba` | 阿里风 / alibaba |
| `fairytale` | 童话 / fairy tale |
| `boardgamestyle` | 桌游 / board game |
| `neonglow` | 霓虹 / neon glow |
| `vintagenewspaper` | 复古报纸 / vintage newspaper |
| `handwrittennote` | 手写 / handwritten note |
| `vintagemap` | 复古地图 / vintage map |
| `blueprint` | 蓝图 / blueprint |
| `botanical` | 植物 / botanical |
| `sketch` | 手绘 / sketch |
| `retro` | 复古 / retro |
| `ayulight` | 简约 / ayu light |
| `bauhaus` | 包豪斯 / bauhaus |
| `greensimple` | 绿意简约 / green simple |
| `maximalism` | 极繁 / maximalism |
| `neobrutalism` | 新粗野 / neobrutalism |
| `newsprint` | 新闻纸 / newsprint |
| `organic` | 有机 / organic |
| `playfulgeometric` | 活泼几何 / playful geometric |
| `professional` | 专业 / professional |

After success, save the resolved `templateId` into `.htmltolink.json` and reuse it on later updates.

## Output handling

- Without an account token: create a temporary markdown page that lasts 24 hours
- With a matching `slug + updateToken`: update the same page and reset its lifetime to 24 hours (updates always use `updateToken`; the `templateId` must be passed again)
- With an account token and no previous page: create a managed (non-expiring) page
- Always create or update `.htmltolink.json` after success
- Save `shareUrl`, `slug`, `updateToken`, `templateId`, `temporary`, and `expiresAt`
- Ensure `.gitignore` contains `.htmltolink.json`; never display or commit `updateToken`
- After updating the config file, return only the final `shareUrl` to the user