Documentation

Publishing the Portal

Publishing has two layers. First a documentation version goes live inside Routebase (Draft → Review → Published). Then the portal build turns that version into a static site your readers can reach. This guide covers taking a version live and everything around it: enabling the portal, controlling visibility, deploying, and sharing.

The forward path — moving a version through review, publishing it, and deploying it to the portal — runs from the Publish button in the documentation header (see The guided publish flow below). Everything else — the portal address, portal features, retracting a version, and taking the portal offline — lives in Documentation Settings → Public Portal.

Those settings are split across five tabs, and it's worth knowing which is which before hunting for a card:

Tab What lives there
Publish Portal Status, Portal Subdomain, Custom Domain, Publication (retract / unpublish), Deployed Versions, Build History
Appearance Theming (the theme editor) and Custom CSS — see Branding
Features The reader-facing feature toggles and the Page actions menu
Advanced SEO and custom head/body scripts
Insights Portal Analytics and the Feedback Dashboard

Every tab except Publish stays hidden until the portal is enabled — they show "The portal is disabled. Enable it in the Publish panel to configure these settings." instead. One Save Changes button at the top of the page saves all of them together, and an amber hint appears while anything is unsaved.

Enabling the portal

On the Publish tab, the Portal Status card has a Portal Enabled switch: "When enabled, your documentation is publicly accessible." Once enabled and published, the card shows your portal URL with an open-in-new-tab link and a copy button, plus the last build status (Completed, Failed, or In Progress) with its page count and date.

If the portal is built but has no public address yet, the card tells you to set a portal subdomain or connect a custom domain first.

Portal subdomain

The Portal Subdomain card (also on Publish) sets your portal's default public address:

  • Allowed characters: lowercase letters, numbers, and single hyphens; 3–63 characters.
  • The name must be globally unique across Routebase.
  • Saving the subdomain requires the docs:manage-portal permission (Admins and Owners).

Once saved and published, your portal is reachable at that subdomain; the resulting URL appears in the Portal Status card.

You can also serve the portal on a domain you own: the Custom Domain card (directly below the subdomain) walks you through DNS records, verification, and SSL, and monitors DNS/SSL health once active. Custom domains are a Pro/Enterprise feature — see Custom Domains for the full setup.

Version visibility

Only published versions that are marked Public can be built for the portal:

  • Internal — the version is only visible to your team inside Routebase.
  • Public — the version can be deployed to the public portal.

Making a version public is part of the guided publish flow's Deploy to portal step. The reverse — retracting a public version — lives in the Publication card on Public Portal → Publish: pick a published version and click Make Internal (requires docs:manage-portal), which removes it from the portal. The confirmation warns: "Visitors will no longer be able to access this version. You can make it public again at any time."

Previewing before you publish

The eye icon in the documentation header generates a real portal preview of the current version and opens it in a new tab, so you can sign off on content before publishing. If a fresh preview already exists it opens straight away (tooltip "Open portal preview"); otherwise clicking it renders one and shows the progress in a popover (tooltip "Generate portal preview"). The preview trigger requires the docs:manage-portal permission.

The guided publish flow

The Publish button in the documentation header opens a guided dialog — "Publish v{N} to your portal" — that walks the version through the whole pipeline in one place. A small pulsing dot on the button, and a tooltip ("Edited since last deploy", "Not deployed yet", or "Up to date"), tells you at a glance whether the live portal is behind your latest edits.

The dialog lists the remaining steps as rows and runs the permitted ones in order when you click the action button:

Stage What it does
Submit for review Moves the version from draft into review.
Publish version / Approve and publish Locks the content (read-only) and archives the currently published version. The row is labelled Approve and publish when an approval workflow is required.
Deploy to portal Makes the version public and publishes your portal (enabling the portal first if needed). Takes 1–2 minutes.

Steps you don't have permission for are shown but skipped, with a note (for example, deploying needs the portal-management permission, and publishing needs the publisher permission). When an approval workflow applies, the dialog names the designated approvers. Once everything is live the dialog says "Everything is live and up to date." and offers an Open portal button.

Deployed versions

Multiple versions can be live on the portal at once (for example v1 and v2 of your API docs). The Deployed Versions card lists each deployed version with its deploy date and page count:

  • Default — the version readers land on. Use Set Default to switch.
  • Undeploy — removes a version from the portal. The last remaining default version cannot be undeployed.

Whether readers can switch between deployed versions is controlled by the Version History feature toggle (below), including a "Versions to show" limit — older versions beyond the limit redirect to the current one.

Retracting and taking the portal offline

The Publication card on Public Portal → Publish handles the retract side: "Retract a published version, or take the whole portal offline." Alongside Make Internal (above), its Unpublish button disables the public portal and removes all published files: "Visitors will no longer be able to access your documentation. You can re-publish at any time."

Portal features

On the Features tab, the Features card toggles reader-facing functionality (remember to click Save Changes at the top of the page):

Feature Description
Search Full-text search across documentation.
API Playground Interactive API request builder. When on, you can pick which project environments (those with a base URL) are exposed as selectable servers in the playground — see Where the base URLs come from.
Code Examples Auto-generated code snippets for endpoints.
Feedback Allow visitors to rate documentation pages.
Table of Contents Show a table of contents sidebar on pages.
Version History Show a version switcher and keep older versions browsable on the portal.
Deprecation Info Show deprecation banners and migration guides for deprecated endpoints.
Show fully qualified schema names Show full schema names (including namespaces) on the portal instead of shortened ones.
Hide Routebase Branding Remove the "Powered by Routebase" footer — requires the Pro plan.

A separate Page actions card on the same tab chooses which entries appear in the portal's "Copy page" menu: Copy page as Markdown, Download OpenAPI spec, Open in ChatGPT, and Open in Claude.

Which languages appear as tabs in the code examples is configured under Documentation Settings → General → Code Languages (cURL, HTTPie, JavaScript, Python, C#, Go, Java, Ruby, and PHP). The portal renders exactly the languages you select — or all of them if you select none. Changing the selection needs a new portal build to take effect.

Where the base URLs come from

The host your readers see in the code samples — and pick from in the playground's server dropdown — is resolved once, at publish time, in this order:

  1. The environments you opted in. With the API Playground on, the environments you ticked under the toggle are exposed, in the order you selected them. Only their name and base URL ever leave Routebase — never their variables or auth configuration. An environment that was deleted, or that has no base URL, drops out silently.
  2. The environment that feeds the public docs. With no opt-in list, Routebase falls back to the project environment carrying the Feeds the public docs role, if it has a base URL. That role is docs-facing by definition, which is what makes it a safe default.
  3. The spec's own servers[]. If neither applies, the samples use the servers declared in the OpenAPI document.

Where a spec declares a base path, it is appended to the environment URL — unless the URL already ends in that path, so https://api.example.com/v3 doesn't become …/v3/v3.

Two consequences worth planning around. The server dropdown lives inside the playground widget, so with the API Playground switched off there is no switcher at all and the code samples silently take the first entry of the resolved list. And if nothing resolves — no opted-in environment, no docs-source environment, no servers[] in the spec — the samples render a literal {baseUrl} placeholder instead of a host.

Docs your readers' agents can read

Every portal build emits three machine-readable outputs alongside the HTML. They are not a feature you switch on; a build that fails to produce them fails outright.

Path What it is
/llms.txt An index of the portal in the llms.txt convention: the site title, the meta description as a blockquote, then two lists — Docs (every content page with a link and a one-line description derived from its own text) and API Reference (every generated endpoint, folder and spec page, in navigation order).
/llms-full.txt The entire portal as one Markdown document — every content page in reading order, snippets resolved, separated by rules. For an agent that would otherwise crawl page by page.
{slug}/index.md A Markdown twin of every page, served next to its HTML. Content pages emit the Markdown you wrote. API reference pages get generated Markdown for the endpoint — path, method, parameters, request and response bodies with $refs resolved — so an endpoint page is readable as text too. Stacked folder and single-page references emit the concatenation of everything they show.

Image paths in llms-full.txt and in the .md twins are rewritten to absolute URLs, because those files get read far away from the page they belong to.

robots.txt points at both the sitemap and /llms.txt, so an agent that starts at the root finds them without being told. The Copy page as Markdown page action (Features tab) is a convenience link to the .md twin for human readers — switching it off removes the menu entry, not the file.

SEO and custom scripts

On the Advanced tab:

  • SEO — set the Site Title, Meta Description, and an OG Image URL (must be an absolute http(s) URL) for search engines and social previews.
  • Custom Scripts — inject Head Scripts and Body Scripts into the portal HTML, e.g. for analytics or chat widgets.

Portal look and feel (themes, colors, fonts, logo, custom CSS) is covered in Branding.

Build history, feedback, and analytics

  • Build History (Publish tab) — every build with status (Success, In Progress, Pending, Failed), version, page count, size, duration, and date. View Log opens the full build log and any error message.
  • Portal Analytics (Insights tab) — page views, unique visitors, search queries, page view trends, top pages, top search terms, and Content Gaps (search terms that returned no results).
  • Feedback Dashboard (Insights tab) — shown when the Feedback feature is on: total feedback, positive rate, trends, and recent comments from portal visitors. The toggle that switches feedback on stays with the other feature switches.
Build history table with a build log dialog open

Publishing from an AI agent

The publish path is available over the Routebase MCP server as well, which is how you'd wire documentation into a release script. The chain is three calls after set_context:

  1. update_doc_page (or create_doc_page) to write the content into a mutable version — Draft or In Review. Needs docs:write.
  2. publish_doc_version to take a version in Review live, archiving the previously published one. Needs docs:publish.
  3. trigger_portal_build to render and upload the portal, which returns the build status and its metrics. Needs docs:manage-portal.

get_portal_url returns the public address and the custom-domain setup status, and the portal-admin toolset covers builds, deployments, analytics and feedback if you want an agent to watch the result. The full tool list is in Documentation Overview.

Publishing straight from the API Designer

When you publish an API spec version, the publish flow's success screen includes a Documentation panel (shown to users with docs:write). It tells you where the spec stands — for example "This API is in documentation v2 (draft), pinned to v1.0.0" — and offers:

  • Update documentation to vX — embeds or refreshes the spec snapshot in a mutable doc version (creating the portal or cloning the live version into a draft if needed). The docs stay a draft until you publish them.
  • Publish documentation (shown with docs:publish) — choose Team only or Public visibility and take the documentation live in one step. Afterwards you get View Documentation and Copy Link buttons for sharing.