API Portal
Portal pages
Create and publish content pages for your API Portal: the Content, Settings and Partials (Beta) tabs, slugs and visibility, publishing, the four protected pages that shape your home and product pages, and what to check before you delete a page.
Pages are the content of your API Portal. You create them under Portal, Pages, write them in Markdoc with a live preview, and publish them. Four built-in protected pages also live here: they lay out your home page and every product's page.
How do you create a portal page?
Choose + Add Page under Portal, Pages. A page called New Page is created, with Visibility off and unpublished, and its editor opens. Give it a title and content, turn Visibility on, turn Published on, and save.
- Open Portal, Pages, then choose + Add Page.
- Type the page title at the top of the editor. The slug, the page's address, follows the title.
- Write the page on the Content tab.
- Open the Settings tab and turn Visibility on.
- Turn the Published toggle on at the top of the editor.
- Choose Save Changes.
The page is then live at your portal address followed by its slug, for example /pricing.
What are the tabs on the page editor?
The editor has three tabs: Content, Settings, and Partials (Beta). On protected pages the Settings tab is locked.
| Tab | What it holds |
|---|---|
| Content | The Markdoc editor with its Insert toolbar, a live preview, the Include Table of Content toggle, and a product picker for previews. |
| Settings | The Slug, a link to the page on your portal, Visibility, and Full width page. |
| Partials (Beta) | Snippets for this page only. Selected Partial picks one, with Rename, Add new, Export, Import and Remove selected. |
How do you write and preview content?
Write Markdoc on the Content tab. The preview beside the editor updates as you type. The Insert toolbar adds images, videos, callouts, links, sections and grids for you. See Markdoc components for every tag.
Include Table of Content adds a table of contents beside the page on screens 1280 pixels and wider, when the page has headings. Protected pages do not have this toggle.
Use the data from the following product to generate preview picks the product the preview uses. It only matters for content that uses the $product variable, such as the Product Page.
How do you set a page's address and visibility?
Open the Settings tab. Slug sets the page's address. Visibility decides who can open the page, and Full width page sets its width. Protected pages lock all three.
| Setting | What it does |
|---|---|
| Slug | The path after your portal address. Use lowercase letters, numbers and single hyphens. It must be unique and cannot be a path the portal already uses, such as products, teams, docs or login. |
| Visibility | On: "Page will be publicly visible." Off: see the note below. |
| Full width page | On: the page uses the full width. Off: a narrower column that is easier to read. |
| Published | At the top of the editor and in the list. On: the page is live. Off: its address shows Page not found. |
Renaming a page changes its slug to match the new title, which changes its address. Update any menu items and links that point to the old address.
How do you publish or unpublish a page?
Use the Published toggle. In the pages list, the toggle in the Status column saves at once. At the top of the editor, it saves with the rest of your changes when you choose Save Changes.
A page must be published to appear on the portal. Filter the list by Status, PUBLISHED to see only live pages.
What are protected pages?
Four built-in pages that the portal looks up by their slug. You can edit their content on the Content tab, but their slug and visibility are locked and the Settings tab says the page is flagged as protected.
| Protected page | What it does |
|---|---|
| Landing Page | Your home page on screens 1280 pixels and wider. |
| Mobile Landing Page | Your home page on narrower screens, including phones, tablets and many laptops. |
| Product Page | The layout of every product's page, on every screen size. |
| Mobile Product Page | Not used for product pages at the moment. Edit Product Page to change them. |
The landing pages read their texts and images from Theme. The Product Page uses the product tags and the $product variable described in Markdoc components.
How do you delete a page?
Open the row menu in the pages list, choose Delete, then confirm in Delete Page. The dashboard does not stop you deleting a protected page or a page that your menus link to, so check both before you confirm.
- Remove the page from Portal, Navigation if it is in a menu.
- In Portal, Pages, open the page's row menu and choose Delete.
- Confirm with Delete.
Troubleshooting
| What you see | What to do |
|---|---|
| "Slug must only contain alphanumeric characters and hyphens. Special characters or spaces are not allowed." | Use lowercase letters, numbers and single hyphens only. |
| "This slug is taken already." | Another page uses that slug, or the portal reserves it, such as products or docs. Choose another. |
| Saving fails after you changed the title | The title produced a reserved or taken slug. Change the title or edit the Slug. |
| The page shows "This page is private." | Visibility is off. Turn it on and save. |
| The page shows Page not found | The page is not published, or its slug changed. Check Published and the Slug. |
| The Settings tab is locked | The page is protected. Edit its content only. |
| Phones show an old home page | They show the Mobile Landing Page. Update it as well. |
| "The usage check of this page failed, please try it later." | The dashboard could not check the page before deleting it. Try again later. |