Dev Portal custom pages

Pages are highly customizable using Markdown Components (MDC), allowing you to create nested page structures to organize pages and generate URLs/slugs. Visibility controls and Publishing status allow you to stage new pages, and/or restrict access to logged-in developers.

To get started creating pages, navigate to your Dev Portal and select Portal Editor from the left sidebar.

Pages are built using Markdown Components (MDC). Additional documentation on syntax, as well as tools for generating components, are available on a dedicated MDC site.

On the left panel inside Portal Editor, you’ll see a list of pages in your Dev Portal. The name for each page is a slug, and will be used to build the URL for that page. If pages are nested, the slugs will be combined to build the URL. This allows you to organize pages, and convey that organization in the URLs of your pages.

Example: about has a child page, contact. The URL for the contact page would be /about/contact

1. In the Dev Portal editor, click New page in the sidebar.
2. Give the page a slug. This will be used in constructing the path. Hit Enter.
3. The page will be created and display in preview.
4. Edit the content of your page in the middle panel, and you’ll see a live preview in the right panel.

To rename a page’s slug, click the ‘three dots’ menu, and click Rename.

Publishing a page

Newly created pages are in Draft status by default. With the page selected on the left sidebar, click Publish in the top right corner, and your page will be published to the Dev Portal.

Changing page visibility

In the top right corner, click the menu with three dots. You can toggle from Private to Public, and vice versa.

Creating a child page

To create pages in a nested structure (generating URLs in a folder-style), you can create Child Pages. Click the three dots menu next to any page, and select Create Child Page. As with creating any page, provide a name and slug, and your page will be created.

The Portal requires a number of reserved paths from the root of the URL to properly function. You can’t override these paths with custom pages or other functionality.

The following table lists the reserved paths:

To affect page metadata/descriptions (meta tags like description og:description), use the description field in page front matter.

For example, using the following front matter, the Portal will render HTML tags for pages:

---
title: Home
description: Start building and innovating with our APIs
---

Will render this:

<title>Home | Developer Portal</title>
<meta name="description" content="Start building and innovating with our APIs">
<meta property="og:title" content="Home | Developer Portal">
<meta property="og:description" content="Start building and innovating with our APIs">

The Dev Portal will automatically generates an Open Graph image for each page on the site which uses a default design, and incorporates your brand color and light or dark color mode, along with the page’s title and description. This image may be used in search results and when sharing links that render page previews (for example, on X or other social sites).

If you would like to provide a custom Open Graph image, you may do so in the page’s front matter by providing the image property as a string:

---
title: Home
description: Start building and innovating with our APIs
image: https://example.com/images/my-image.png
---

If you would like more control over the image, the front matter property also accepts an object interface:

---
title: Home
description: Start building and innovating with our APIs
image:
  url: https://example.com/images/my-image.png
  alt: A description of the image
  width: 300px
  height: 200px
---