Skip to content

sharing.md

Latest commit

 

History

History
89 lines (63 loc) · 3.34 KB

sharing.md

File metadata and controls

89 lines (63 loc) · 3.34 KB
Raw

Sharing & access

Every document has one canonical share link — https://htmlbook.io/d/{shortId} — minted once at first publish. The same link behaves three ways depending on the document's visibility — public, password-protected, or private (secret).

Private by default

Nothing is public until you say so. A freshly published document is private: only you (and your workspace members) can open it, after signing in.

The publish response reflects this — you always get your own reader link, and the public share link only when it actually resolves:

shelved (hbdoc) · acme/q3 · v1 · read: https://htmlbook.io/app/p/acme/q3
  private — set_access "public" for a share link

Make it public

set_access flips visibility and returns the share link when public:

{ "tool": "set_access", "project": "acme", "slug": "q3", "visibility": "public" }
acme/q3 is now public · https://htmlbook.io/d/a1b2c3

  • Public ("public"): anyone can open /d/{shortId}, no login. Mirrored to the edge for fast loads and indexed for SEO.

  • Password ("password"): anyone with the link and the password can open it — no login, just the password. Pass a password to set_access; visitors get a password prompt at /d/{shortId}. Changing the password later revokes everyone who already unlocked it. Never indexed, never edge-mirrored.

    { "tool": "set_access", "project": "acme", "slug": "q3", "visibility": "password", "password": "hunter2" }

  • Secret ("private"): the same link is session-gated. Anonymous visitors are sent to log in; signed-in non-members see an unavailable page; you and your workspace members get the document. Always noindex.

Flipping back to private/public removes the public copy and clears any password — the link reverts accordingly. Copying a link never changes visibility.

Two ways to read the raw source

  • Owner: GET https://htmlbook.io/api/docs/source?project=…&slug=… (Markdown docs).
  • Public doc: GET https://htmlbook.io/d/{shortId}/raw.

Versions & history

Every publish and every in-reader edit is a new immutable version. The reader's History panel lists versions with who changed what (agent push vs. web edit, with precise before/after text) and can diff any two. Bodies are immutable, so a diff between any pair is always available.

Restore an earlier version with the restore tool (owner-only):

{ "tool": "restore", "project": "acme", "slug": "q3", "version": 3 }

Workspaces & members

Documents group into projects, and projects live in workspaces. A workspace has one owner and any number of editor members.

  • Invite members with a link from Settings → Members (/join/{token}, 7-day expiry, one live link per workspace, revocable).
  • Editors can read every document and project in the workspace, and fix text in the reader (each edit versioned under their name).
  • Owner-only: API keys, visibility, organize, restore, and trash/purge.

An API key is bound to one workspace; new projects published with that key land there.

Trash

delete is a soft delete — the document moves to the trash, where the owner can restore or permanently purge it:

{ "tool": "delete", "project": "acme", "slug": "q3" }

See also: Publishing · MCP tools