Publish to dochost

turn markdown or html into a hosted web page at its own url, in one call. the page renders live (markdown and html), so the recipient sees a real page, not a raw .md blob. free links last 7 days; permanent links, passwords, custom slugs and branding removal follow the account's plan.

intent

publish user-generated markdown or html to dochost.io, a document hosting service, and return a shareable public url. use this when the user says "publish this", "share this as a link", "put this on the web", "make a page from this", "turn this into a link", or equivalent in other languages. works for any document, report, readme, or html the assistant produced. the skill runs on any agent that can make http requests (openai, anthropic, cursor, or shell).

inputs

environment variable (required):

• DOCHOST_API_KEY: api key from dochost.io account. obtain it by signing in at https://dochost.io, opening settings, api keys, and creating a new key. the key authenticates all requests and determines plan entitlements (link lifetime, password protection, custom slugs, branding removal).

procedure inputs:

• body (string, required): the markdown or html content to publish.
• format (string, optional): either "markdown" or "html". auto-detected when omitted; set explicitly if content is ambiguous (e.g., a markdown string that contains html tags).
• public (boolean, optional): list the page on dochost explore. default false (unlisted, private link).
• customSlug (string, optional, paid feature): custom url path (lowercase, numbers, hyphens only) instead of a random slug. requires paid plan.
• password (string, optional, paid feature): gate the page behind a password. requires paid plan.
• noBranding (boolean, optional, paid feature): hide the dochost footer badge. requires paid plan.

external connection:

• dochost.io mcp endpoint: https://dochost.io/api/mcp (stateless, no handshake required).

edge cases to handle:

• api key missing or expired: http 401 response.
• rate limiting: http 429 response with retry-after header.
• quota exceeded (free plan limits page count and size): http 402 or 400 with message field.
• network timeout: no response within 30 seconds.
• oversized body: free and paid plans have document size limits.
• blocked url: content contains unsafe or flagged link.
• custom slug taken or invalid: must be lowercase, alphanumeric, hyphens only.

procedure

1. validate inputs: check that DOCHOST_API_KEY env var exists and is non-empty. if missing, stop and tell the user to set up the key first (see intent section for setup link).

2. prepare request body: construct a json-rpc 2.0 call with method tools/call and params {"name": "publish", "arguments": {...}}. include body (required) and format if provided or auto-detect. include public, customSlug, password, noBranding only if the user explicitly requested them.

3. send http request: post to https://dochost.io/api/mcp with headers:

   • Authorization: Bearer $DOCHOST_API_KEY
   • Content-Type: application/json
   • Accept: application/json
   • timeout: 30 seconds.

4. parse response: extract the response body as json. check for http status code (200 ok, 401 auth error, 429 rate limit, 402/400 quota/validation error, 5xx server error).

5. extract payload: if status is 200, parse result.content[0].text as json (it is a json string, not raw json). if parse fails, inform user that dochost returned malformed response.

6. read success fields: from the parsed payload, extract:

   • url: the public dochost.io/d/... link.
   • expiresAt: the expiration timestamp (null means permanent).
   • editToken: the token for later edits (store if user may want to edit; do not expose to end user unless requested).
   • slug: the generated or custom slug.

7. read error fields: if ok is false, extract the message field (plain-english error text written for end users).

8. return to user: on success, hand back the url as the primary result. mention expiresAt if set (e.g., "this link expires on [date]"). on error, relay the message verbatim without paraphrasing.

decision points

if api key is missing or invalid:

• stop. direct user to https://dochost.io, settings, api keys, create a key, and set DOCHOST_API_KEY env var. do not retry or fall back to unauthenticated publishing (it is disabled by design).

if http status is 401 (unauthorized):

• the key is invalid, expired, or revoked. tell user to check the key and refresh it if needed.

if http status is 429 (rate limited):

• extract the retry-after header (seconds to wait). tell user "too many publishes, wait [N] seconds before trying again". do not retry automatically; let user decide.

if http status is 402 or 400 with quota/validation error in message:

• if "quota" or "limit" appears in message: user has hit plan limits (page count, size, or feature). tell user to delete old pages or upgrade.
• if "customSlug" in message: the slug is taken or invalid. suggest a different slug (lowercase, numbers, hyphens, no underscores or spaces).
• if "blocked url" in message: the content contains an unsafe link. ask user to remove or replace the link.
• relay the message verbatim.

if http status is 5xx (server error):

• dochost is temporarily unavailable. tell user to retry in a few seconds. do not loop; ask user to try again manually.

if response parse fails or payload structure is unexpected:

• log the raw response (for debugging). tell user "dochost returned an unexpected response; try again in a moment or contact support".

if user requests a paid feature (customSlug, password, noBranding) but the account plan does not support it:

• the api will reject the call with an error message (e.g., "custom slug is a paid feature"). relay the message and suggest upgrading.

if body is very large (>10 MB):

• warn user before sending: "this content is large and may exceed plan limits; proceed?" let user decide.

if format is ambiguous (e.g., html-like markdown or markdown with html tags):

• ask user to clarify format, or set format to the suspected type explicitly.

output contract

on success:

• return object with fields:

  • ok: true
  • url: string, the public dochost.io/d/{slug} link (e.g., "https://dochost.io/d/q3-report")
  • slug: string, the generated or custom slug
  • expiresAt: string (iso 8601 timestamp) or null if permanent
  • editToken: string (only if user may edit later; not exposed to end user by default)

• hand the url to the user as the primary artifact. format as a clickable link if possible.

• if expiresAt is not null, include in the message: "this link expires on [date]".

on error:

• return object with fields:

  • ok: false
  • message: string, plain-english error description (user-facing, no technical jargon)

• relay the message verbatim. examples:

  • "rate limited, wait 60 seconds"
  • "free plan limit reached, delete a page or upgrade"
  • "custom slug 'my-page' is taken"
  • "content contains a blocked url"

file location / artifact:

• no file is written locally. the published page lives at the returned url.

outcome signal

the user knows the skill worked when:

• they receive a clickable https://dochost.io/d/{slug} url.
• they open the url in a browser and see the content (markdown rendered as html, or html displayed as-is).
• the page is live and shareable immediately (no email confirmation or build step).
• if expiresAt is set, they know when the link will expire.

the user knows the skill failed when:

• they see an error message (e.g., "rate limited", "quota exceeded", "invalid slug") without a url.
• they click the url and receive 404 (page not found, likely expired or slug conflict).
• the response is slow or times out (>30 seconds).