Public Documentation Site

SelfDocHub can publish the documentation of all or some of your services as a public site that anyone can read without signing in. This page explains the parts involved and the steps to get a site online.

Roles: The Publishing section is for admin and editor. Domains and styles are managed by an admin; an editor publishes versions of the services in their teams only. It needs the publish feature in your license (Team tier and above). See License and Tiers.

How it works#

Three parts work together:

  1. SelfDocHub (the hub). In the Publishing section you choose the services, build a published version and design the site. A published version is a frozen, independent copy of the documentation, so the public site never touches your live data, tokens, environments or saved requests.
  2. The public API. A read-only API under /public/v1 serves the published copy. It needs no sign-in. Every request names its site in the X-Public-Domain header. See Public API and Limits.
  3. The portal. A separate Nuxt application, self-doc-hub-portal, reads the public API and draws the site: the version menu, pages, endpoints, search, the light and dark theme and the language switcher. One portal installation can serve several domains. See Deploy the Public Site.

You can see a live example at docs.demo.selfdochub.com: the three demo services of demo.selfdochub.com, published with a custom style.

Readers talk to the portal only. The portal talks to SelfDocHub on the server side, so you do not have to expose or configure anything of the hub for browsers.

What gets published#

  • The services and service versions you pick, with the structure, text pages and Markdown overlays as readers see them in the hub.
  • Page pictures.
  • Request and response examples only if you switch them on for the version, because examples can contain secrets.

Environments, tokens, saved requests and notes never get into a published version.

Getting a site online#

  1. License. Check that your license includes publish. The License page lists it, with the limits for domains and versions.
  2. Portal. Run the portal and point it at your SelfDocHub. See Deploy the Public Site.
  3. Domain. In Publishing → Domains, add the host the site will be reachable on, for example docs.example.com. See Publishing Domains.
  4. Style. Optionally create a style with your colors, logos, top bar and footer and assign it to the domain. See Styles, Branding and Design Tokens.
  5. Version. In Publishing → Versions, add a version, choose the services and show it. See Published Versions.

A new version starts hidden. Open it with a preview link, check it, then show it.

Limits by plan#

Free Team Business Unlimited
Documentation publishing no yes yes yes
Domains – 1 5 no limit
Versions per domain – 5 20 no limit

The limits stop creating more. Existing domains and versions are never deleted when a limit is lowered. See License and Tiers.

Next steps#

Screenshots

Last updated: