Publishing Overview

Publishing in Unmarkdown means turning your Markdown document into a live, hosted web page. Your document gets a unique URL that anyone can visit, and it stays available as long as you keep it published.

There is no build process, no deploy step, and no external hosting to configure. Click Publish, and your page is live.

When you publish a document, Unmarkdown runs it through a rendering pipeline:

• Your Markdown source is parsed into an abstract syntax tree
• Plugins process extensions: callouts, diagrams, math, emoji, and icons
• The AST is converted to HTML
• Your selected template's CSS is generated and applied server-side
• The styled page is served over HTTPS with global CDN delivery

Published pages use Incremental Static Regeneration (ISR) with a 3600-second (1-hour) revalidation interval. The first visitor after revalidation triggers a background rebuild, so pages stay fast while reflecting your latest changes.

Published documents are accessible through two URL formats:

Username URLs (Primary)

https://unmarkdown.com/u/yourname/getting-started-guide
https://unmarkdown.com/u/yourname

If you have set a username, your documents live under /u/[username]/[slug]. Your profile page at /u/[username] lists all your publicly visible documents.

Direct URLs

https://unmarkdown.com/d/abc123

Every document also has a direct URL at /d/[slug]. This works regardless of whether you have set a username.

Every user with a username gets a public profile page at /u/[username]. The profile displays your display name, bio, and avatar, along with a grid of your publicly visible published documents. Visitors can browse your documents and click through to read them.

Every published page includes the following:

• Responsive layout that adapts to desktop, tablet, and mobile screens
• Template CSS applied server-side for full SEO and social card fidelity
• Automatic SEO metadata generated from your document title and content
• Open Graph and Twitter Card tags for rich social media previews
• Auto-generated OG images via @vercel/og with your template's accent colors
• JSON-LD structured data (Article schema)
• HTTPS with no configuration required
• An Unmarkdown badge on free-plan documents (hideable on Pro)

In the editor, click the Share button in the top bar to open the share modal. Switch to the Publish tab to configure your document's URL, visibility, page width, and other settings. Click Publish to make it live. Re-publishing updates the live page instantly.

You can also publish documents through the REST API. Use POST /v1/documents/:id/publish to publish an existing document, or include publishing parameters when creating a document with POST /v1/documents.

curl -X POST https://api.unmarkdown.com/v1/documents/doc_abc123/publish \
  -H "Authorization: Bearer um_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-guide",
    "visibility": "link"
  }'

To publish a document, you need an Unmarkdown account. Both free and Pro plans support publishing. The free plan allows up to 5 documents and up to 3 published pages (the welcome template does not count toward this limit), while the Pro plan supports unlimited documents and published pages.

You do not need to choose a template before publishing. Unmarkdown applies the default Swiss template if you have not selected one. You can change the template at any time and re-publish to update the live page.

You can unpublish a document at any time to take it offline. Unpublishing removes the public page but keeps your document and all its settings intact. You can re-publish later with the same URL if desired.

To unpublish via the API, send DELETE /v1/documents/:id/publish.