Documentation Overview

Routebase turns your API specs and hand-written guides into a versioned documentation portal. Each project has its own documentation workspace where you organize pages, folders, and API references in a single content tree, then publish the result as a hosted portal for your readers.

Open Documentation in the sidebar while a project is active. Viewing documentation requires the docs:read permission; making changes requires docs:write (both are included in the built-in Member role).

Your first visit

What happens the first time a project has no documentation depends on what you're allowed to do with it.

If you can complete the whole setup — you hold docs:write, docs:manage-portal and docs:publish, which Admins and Owners do — Routebase opens a three-step assistant, "Set up your documentation portal":

1. Content — give the portal a name and tick the API specs you want embedded as an API reference. Draft-only specs show Publish & add and are published on the way in (that needs specs:publish); a spec with no publishable version at all is shown disabled as No version. The step creates a Getting Started page from an editable template as the portal's entry page.
2. Branding — save the portal address (the subdomain, required to continue) and pick one of the built-in themes. Colors, fonts and logo are left for the theme editor later.
3. Go Live — a summary of name, address, theme and content, then Publish portal. That makes version 1 public, enables the portal and starts the first build; you land on the live URL and can keep editing afterwards.

Skip setup — go to the editor at the bottom leaves the assistant at any point and drops you into an empty documentation workspace instead.

Members who can edit but not publish or configure the portal never see the assistant — for them a documentation workspace with an initial draft version is created silently, and the portal side is left to someone who can do it.

The version overview

Opening Documentation — and every switch to another version — lands on Overview, the first entry above the content tree. It answers "where does this version stand" without a trip through the settings pages, and you can return to it at any time by clicking that entry.

Status header. The version number and its status badge, the last build (a colored dot with Build succeeded / failed / building / queued), and one line of context: Published 3 days ago, Draft — not published yet, In review — waiting for approval, or Archived — read-only. When the portal is enabled, its public URL sits below with a copy button. The action on the right follows the version: an editable version offers Publish, a read-only one offers Open portal and Clone to new version.

Needs attention lists only what is actually pending, and each entry carries the action that resolves it:

Entry	When it appears	Action
"<Spec> has a newer published version (vN)"	An embedded API reference is behind its spec — one entry per affected reference, only on an editable version	Review update opens that reference
"The last portal build for this version failed"	The newest build of this version failed	View build log
"N reader feedback entries this week (portal-wide)"	Readers left feedback in the last 7 days	Review feedback

Dismissing a spec-update banner in the reference view also removes it here. When nothing is pending, the whole block collapses to a single line: "Everything is up to date."

Stats count Pages and API references in this version, plus Endpoint coverage — how many embedded endpoints carry a description, as 12/40 with the percentage below. Portal views (last 7 days, portal-wide) appears only for readers with docs:manage-portal; everyone else sees three tiles instead of four, and no request is made for data they may not see.

Recently edited lists the pages that moved last, each with the person who touched it and when. Clicking a row opens that page.

A version with no content at all shows entry cards instead — Add a page, Add an API reference, Start from template (which seeds a Getting Started page). On a read-only version the cards are replaced by the note that it must be cloned before it can be edited.

How documentation is structured

Concept	What it is
Documentation	The container for all docs of a project. It holds versions and the portal configuration.
Version	An independent snapshot of the whole content tree (v1, v2, …). Drafts are editable; live versions are read-only. See Versioning.
Page	A single document — either a free-form custom page or a specialized page type (Getting Started, Authentication, …).
Folder	Groups pages in the tree. Root-level folders can be promoted to sections, which become top-level navigation tabs.
API Reference	An embedded snapshot of a published API specification, rendered as endpoint reference pages.

The content tree

The left sidebar shows the content tree for the selected version. At the top of the tree:

• The Content header with a + menu: New Page, New Folder, Add API Spec, and New Section.
• A Filter... box that narrows the tree by page title, folder name, spec name, or endpoint path/method. Press Escape to clear it.

The sidebar header has a Search (⌘K) button, and a Settings button is pinned at the foot of the sidebar (it opens Documentation Settings). Generating a portal preview and publishing are handled from the documentation header at the top of the page — see Publishing.

Items without a section render under two group labels, Pages and API Specifications. When the tree is empty you'll see "No content yet — Start building your documentation." with a New Page button.

Organizing the tree

• Drag and drop items to reorder them or move them into folders.
• Right-click any item for the context menu: New Page, New Folder, Add API Spec, Rename (also F2 or double-click), Edit Slug, Duplicate (pages only), Move Up / Move Down, and Delete (or Remove for API specs). Deleting asks for confirmation and cannot be undone.
• Root-level folders offer Mark as Section / Unmark as Section. Sections render as collapsible groups in the editor tree and as separate navigation areas in the published portal.

The folder overview

Clicking a folder or section name opens its own working surface on the right; the chevron still expands and collapses. (Clicking the name only ever expands — so the surface doesn't disappear under the click that opened it.)

• Header — the folder name (double-click to rename), its slug, and a Section · portal tab badge for sections. If pages below it changed since the last successful portal build, an amber line says how many. Add page and Add subfolder sit on the right, with Rename, Edit slug and Delete behind the ⋯ menu.
• Description — a text field that saves when you click away. On a section it doubles as the intro of the portal tab, and the hint below says so.
• Stats — Pages (including subfolders), Changed since publish (with the time of the last build, or never published), and Last edited with the person who did it.
• Contents — the folder's direct children as a list. Drag the handle to reorder; this is the same operation as dragging in the tree, so both show the same order once you let go. Subfolders show the number of changed pages they contain; a page with no content yet is marked · empty. An empty folder says so instead, with an Add your first page button.
• Portal — for a section, and only once the portal has an address, a last row shows where that tab lives and links to it.

"Changed since publish" compares each page's last edit against the last successful portal build. Reordering alone doesn't count as a change — the marker follows the pages, not their order.

Read-only versions show the same surface without the input fields, the drag handles and the actions.

Pages and page types

Choosing New Page opens a type picker. Custom pages are free-form; the eight specialized types are structured starting points that can each exist once per version (the card is disabled with an "Already exists in this version" tooltip and a "Go to page" shortcut when taken):

Page type	Purpose
Custom Page	Free-form content with the rich text editor.
Getting Started	Prerequisites, installation, and first API call.
Authentication	Auth methods, configuration, and code examples.
Environments	Base URLs and environment configuration.
Error Codes	Error table, categories, and handling examples.
Rate Limits	Rate limit tiers, headers, and retry strategy.
Webhooks	Events, payloads, verification, and retry policy.
SDKs & Libraries	SDK cards, install commands, and quick start.
Changelog	Version history with categorized entries — see Changelog.

Every type opens with a template picker — see Page Templates. All pages are edited with the same rich text editor — see Authoring.

On the Free plan, each documentation version can contain up to 3 custom pages. The count is per version, so a new version starts with a fresh budget, and the eight specialized types don't count against it — they have their own once-per-version rule. Once the budget is used up, the New Page dialog refuses a further custom page and points at an upgrade. Paid plans have no limit.

API reference pages vs. custom pages

Custom pages are content you write. API reference pages are generated from your API specs:

1. In the tree's + menu, choose Add API Spec.
2. Pick a specification from the project. Only specs with a published version can be added (drafts show a "No Published Version" badge); specs already in the tree show "Already added".
3. Optionally check Enable API Playground to let readers send live requests from the reference pages.
4. Choose the Endpoint Structure: Folder-based (grouped by the spec's folders or tags) or Flat List.
5. Click Add Specification.

The spec is embedded as a snapshot pinned to the published version — later spec edits don't silently change your docs. When a newer published spec version exists, a banner appears on the reference view: "API Reference pinned to vX. Version vY available." with an Update button. You can also switch a spec node between folder and flat view from its context menu, and drag-reorder its endpoints and groups directly in the tree.

Selecting the spec node opens a scrollable reference of every endpoint, with a header card showing the endpoint count and whether the playground is enabled. In editable versions, each endpoint has a collapsible Notes field for adding documentation-side annotations without touching the spec itself.

Slugs

Every page and folder has a URL slug used in the published portal and in navigation. Slugs contain only lowercase letters, numbers, and single hyphens.

• Slugs are generated from the title when you create a page or folder, but you can override them in the creation dialog.
• Renaming an item later does not change its slug. To change it, use Edit Slug in the context menu — the dialog notes that existing links to the published page keep using the slug they were published with.

Searching your documentation

Press ⌘K (or click the search icon) to open documentation search. Type at least two characters, then filter results by All, Pages, Endpoints, or Folders. Selecting a result jumps to it in the tree. Search works in draft versions too — Routebase builds a local index from the tree until the version is published.

Documentation settings

The Settings button at the foot of the sidebar opens Documentation Settings with three tabs:

• General — version numbering scheme, approval workflow, Schema Display, and the Code Languages shown as tabs in code examples (cURL, HTTPie, JavaScript, Python, C#, Go, Java, Ruby, and PHP). Only the languages you select are rendered, in the app and on the published portal; select none to show all of them. See Versioning for the versioning options.
• Public Portal — everything about hosting and publishing the portal, itself split into five tabs: Publish, Appearance, Features, Advanced, and Insights. See Publishing.
• Snippets — the reusable content snippets for the selected version.

Schema Display controls how schema names appear in the API reference (display only — the OpenAPI export keeps the original names). Choose a Display Mode: Full names (exactly as imported), Short names (just the last segment, keeping a minimal namespace prefix only where names collide), or Strip prefix (remove a namespace prefix you specify). The public portal shows short names by default; the Show fully qualified schema names toggle under Public Portal → Features overrides that for readers.

Working on documentation from an AI agent

The documentation module is fully exposed over the Routebase MCP server, so an agent can read and write your docs with the same permissions your API key carries. It is not a read-only view of the portal — the whole authoring loop is there.

Three toolsets cover it (enable them with enable_toolset, and call set_context for the project first):

Toolset	Slug	What it covers
Documentation	documentation	30 tools for the content tree, pages, folders, versions, spec snapshots and snippets
Portal Administration	portal-admin	10 tools for portal settings, custom domains, builds, deployments, analytics and page feedback
Portal Docs Search	portal-docs	2 read tools against a published portal

The tools you'll reach for most:

• Read the structure — get_doc_tree returns the folders, pages and spec snapshots of a version as a typed hierarchy; list_documentations and get_doc_settings cover the surrounding configuration.
• Write content — create_doc_page and update_doc_page take Markdown directly. Updating a page can also set a new slug, and the old one then redirects on the published portal. Both only work on a mutable version (Draft or In Review); a live version is refused, exactly as in the editor.
• Restructure — manage_doc_tree, manage_doc_folder and manage_doc_page handle moving, renaming and deleting; manage_spec_snapshot embeds and refreshes API references; manage_doc_version and clone_doc_version handle the version lifecycle.
• Ship it — publish_doc_version takes a version in Review live, and trigger_portal_build renders and uploads the portal. See Publishing.
• Read a published portal — search_portal_docs does keyword search across the latest published version and returns slugs; get_portal_page then returns one page with its full Markdown. Useful for agents that consume your docs rather than write them.

Permissions map one-to-one onto the ones described above: reads need docs:read, writes docs:write, publish_doc_version needs docs:publish, and anything touching the portal itself needs docs:manage-portal. A key without a scope doesn't just fail the call — the tool isn't offered in the first place.

There is also an MCP resource, routebase://docs/{docId}/pages, which hands an agent every page of the latest published version with its Markdown content in one read.

Read-only versions

Live and archived versions are immutable. The tree shows a "This version is read-only" indicator, pages open in reader mode, and all editing affordances are hidden. To make changes, clone the version into a new draft — see Versioning.

Related

• Authoring — the rich text editor, blocks, and slash commands
• Versioning — drafts, review, and going live
• Publishing — hosting the portal
• Endpoints — designing the API specs your references are built from
• MCP Quickstart — connecting an AI agent to this workspace