Dev Portal pages and content

In your Dev Portal, you can create pages that contain content such as text, buttons, tabs, and more. Pages are used to convey information about your API and Dev Portal to users. They are highly customizable using Markdown Components (MDC), allowing you to create nested page structures to organize pages and generate URLs or slugs. You can also stage new pages or restrict access to logged-in developers by using visibility controls and publishing status.

Figure 1: The Portal Editor UI in Dev Portal.

You can create multiple pages in the Dev Portal, similar to how a website is structured. Pages can contain text and other objects, like containers and buttons. To get started creating pages, navigate to your Dev Portal and click Portal Editor in the 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.

Page structure

On the left panel inside the 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. You can nest child pages under other pages. If pages are nested, the slugs will be combined to build the URL.

For example, if about has a child page called contact, its URL will be /about/contact.

about         ← URL: "/about"
└ contact    ← URL: "/about/contact"

Page visibility and publishing

You can choose to make a page public or private and publish or unpublish it. To control page visibility and publishing, click a page in the Portal Editor and click the menu at the top right.

Reserved paths

Dev Portal reserves certain 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:

Metadata

Dev Portal will use the front matter you set in a page, like the title and description, and render HTML tags.

For example:

---
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">

OpenGraph

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

If you would like to provide a custom Open Graph image, you can specify it in the page’s front matter with 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
---

You can reuse content on multiple pages by using snippets. Snippets allow you to store and write content in one location and use that content in multiple pages. You can also use snippets to publish content temporarily, like system outages or special events.

Snippets are built using Markdown Components (MDC). See the dedicated MDC site for more information about Snippet syntax and usage.

To get started creating snippets, navigate to your Dev Portal and click Portal editor, then click Snippets.