Content
Documentation hubs
Build multi-page documentation sets on your API Portal. You create a hub by giving it a name, then add categories and pages in Markdoc, each with its own visibility. Your plan sets how many hubs you can have, the default hub included.
A documentation hub is a multi-page documentation set on your API Portal. You manage hubs under Content, Documentation. Each hub has categories and pages, shown to readers with a navigation sidebar. Every portal has a default hub, Documentation, at /docs.
How do you create a documentation hub?
Choose Add another Documentation Hub, enter a name, and choose Save Changes. The dialog asks only for a name. Apiable builds the slug from it and shows a preview of the hub's address.
- Open Content, Documentation.
- Choose Add another Documentation Hub.
- In Create a new Documentation Hub, enter the Documentation Hub Name. The dialog previews the address under "Your documentation hub is currently located at:".
- Choose Save Changes. The hub appears in the list with its slug.
- Select the hub's name to open it and add pages.
Apiable makes the slug by replacing spaces with hyphens and lowercasing the name. Use letters, numbers and spaces in the name. If the name has other characters, check the Slug column after you create the hub, and change the slug with Edit before you add pages.
How do you rename a hub or change its slug?
Open the hub's row menu and choose Edit. The name and slug become editable, each with its own Update button. Choose Cancel to stop editing. The default Documentation hub cannot be edited.
The slug rules apply when you edit it:
| Rule | Message when it fails |
|---|---|
| 3 to 50 characters | "Slug must be between 3 and 50 characters long" |
| Lowercase letters, numbers and hyphens, not starting or ending with a hyphen | "Slug can only contain lowercase letters, numbers, and hyphens, and cannot start or end with a hyphen" |
| Different from every other hub's slug | "Slug must be unique" |
Renaming a hub keeps its slug and its address.
What happens when you change a hub's slug?
The hub moves to its new address, but its pages stay stored under the old one until someone saves the hub. Until then, readers who open those pages at the new address get a not-found message. Open the hub and save it right after you change the slug.
- Change the slug with Edit and Update.
- Select the hub's name to open it. A notice says that some pages have malformed slugs and will be auto-corrected on save.
- Choose Save Changes. The pages move to the new address, and a notice confirms how many were corrected.
- Update any links to the old address, in your navigation, pages and articles. They stop working once the pages move.
How do you add and arrange pages in a hub?
Open a hub to reach its Documentation Settings editor. The sidebar lists the hub's categories and their pages. Choose Add new category for a category and Add section inside a category for a page. Drag categories and pages to reorder them.
| Page setting | What it does |
|---|---|
| Visibility | Click to cycle through Private, Protected and Public. See the next section. |
| Published | Whether the page is on your portal at all. |
| Title | The page name shown in the navigation. |
| Slug | The last part of the page's address. The preview under the field reads "Your section URL is:". |
| Editor | The page content, written in Markdoc. |
| Page Preview | Renders the page as readers will see it. |
| Show changes | Compares your edits with the saved version. |
Choose Save Changes to save your edits to every page in the hub at once. Save before you choose Back to List or leave the editor: unsaved edits are lost when you leave, without a warning.
Who can see a documentation page?
Each page's Visibility decides what readers who are not signed in get. Signed-in users of your portal see every published page. A page must be Published to appear on your portal at all.
| Visibility | Readers who are not signed in | Signed-in users |
|---|---|---|
| Public | See the page. | See the page. |
| Protected | See the title in the navigation, and a prompt to sign in instead of the content. | See the page. |
| Private | Do not see the page. | See the page. |
What does Show all pages of a collection in single view do?
It shows documentation as one continuous scroll instead of one page at a time. It is one setting for every documentation hub on your portal, the default hub included, even though the label says "a collection". It sits above the hubs list and saves as soon as you switch it.
With it on, a reader who opens a page sees that page followed by every later page in the hub's order that they are allowed to see. With it off, each page shows on its own, with links to the previous and next page.
Where do documentation hubs appear on your portal?
The default Documentation hub is at /docs, and its pages at /docs/page-slug. Every other hub is at /docs/hub/hub-slug, and its pages at /docs/hub/hub-slug/page-slug. Opening a hub's address shows its first page.
| What | Portal address |
|---|---|
| The default Documentation hub | /docs |
| A page in the default hub | /docs/page-slug |
| Any other hub | /docs/hub/hub-slug |
| A page in any other hub | /docs/hub/hub-slug/page-slug |
How do you delete a hub?
Open the hub's row menu, choose Delete, then confirm in Delete the Documentation Hub. Deleting a hub does not delete its pages. The default Documentation hub cannot be deleted.
To take a hub's content off your portal, open the hub and delete or unpublish its pages first, choose Save Changes, then delete the hub.
Troubleshooting
| What you see | What to do |
|---|---|
| Add another Documentation Hub is disabled and the list says you have reached the maximum | Your plan's hub allowance is used up, and the default hub counts toward it. Delete a hub you no longer need, or contact Apiable about your plan. |
| A banner says your account does not have the role to manage approval groups | On this page it means your role cannot manage documentation hubs. Ask an Organisation Admin for the Portal Admin role. |
| "Slug must be between 3 and 50 characters long" | Use a slug of 3 to 50 characters. |
| "Slug can only contain lowercase letters, numbers, and hyphens, and cannot start or end with a hyphen" | Remove other characters, and any hyphen at the start or end. |
| "Slug must be unique" | Another hub already uses that slug. Choose a different one. |
| A notice says some pages have malformed slugs and will be auto-corrected on save | The hub's slug changed since its pages were saved. Choose Save Changes to move the pages to the hub's current address. |
| Pages in a hub show a not-found message on the portal | If you changed the hub's slug, open the hub and choose Save Changes. Otherwise, check that each page is Published. |
| Save Changes stays disabled after you edit a page | Look under Slug for "Slug must be at least 3 characters long" or "Invalid value. Slug must contain only alphanumeric characters.", and give two pages in the hub different slugs. If the hub's own slug has characters other than lowercase letters, numbers and hyphens, change it with Edit first. |
| "Error updating/creating/deleting docs pages" after you save | Check each page you changed for "Slug must be unique, slug already in use." under Slug. Change that slug, then save again. |
| Edits to a page disappeared | They were not saved before you left the editor. Make them again and choose Save Changes. |
| Edit and Delete are disabled on a hub | It is the default Documentation hub. Manage its pages from its editor. |
Where to next
Content overview
See everything you can publish on your portal beyond product docs.
Markdoc components
The components and variables you can use in your pages.
Articles and collections
Publish standalone posts grouped into collections instead of a documentation set.
Media repository
Upload the images and videos your documentation pages use.