Pages

Layout Options

Customize a page layout's sidebars with snippets, or hide them, through the layout-options front matter property.

Overview

The layout-options property is defined in the front matter of a Page. It replaces the Page's sidebars (the left sidebar and the right sidebar) with the content of a Snippet. A region can also be set to false to hide it, so the Page renders without that sidebar.

This property was previously named page-layout. That name is deprecated and still works, but it logs a warning to the browser console. Please rename page-layout to layout-options in your existing Portal Pages' front matter.

---
title: "Guides"
layout-options:
  sidebar-left: "guides-sidebar-left"
---
  • sidebar-left
  • sidebar-right

The sidebar regions allow you to configure a responsive "2 column" or "3 column" layout which is commonly used in Dev Portal documentation, guides etc.

You can choose to configure either of the sidebars independently (left or right), or choose to configure both for a 3-column layout. An example of the 3-column layout can be seen in the Dev Portal's API documentation pages.

Sidebars must refer to a Snippet. The content of each sidebar will be defined in the referenced Snippet.

Set a sidebar region to false to hide it. The Page then renders with no sidebar at all in that position: no Snippet, no navigation, and no table of contents. This is useful when a Page needs more room for its content.

---
title: "Guides"
layout-options:
  sidebar-left: false
---

A hidden sidebar shows no interactive APIs list filter either. Do not set a sidebar to false on a Page that uses show-filter.

Usage

Page

In the example Page front matter below, the guides-sidebar-left and guides-sidebar-right refer to the name of the Snippets. Simply define the name of the desired snippet(s) in the layout-options property of the front matter.

---
title: Guides
layout-options:
  sidebar-left: "guides-sidebar-left"
  sidebar-right: "guides-sidebar-right"
---

Snippet

The guides-sidebar-left Snippet in this example would provide navigation between Pages, a typical layout pattern. Here's an example of the snippet content:

Notice we are defining a title property in the front matter of the Snippet. This is used to set the title of the sidebar navigation toggle button on smaller screens, set here to Guides.

---
title: Guides
---

::page-navigation
---
header: "Flights Information"
href: "/guides/flights"
children: true
---
::

The guides-sidebar-right Snippet in this example would provide a table of contents of sections within the current page, using the Page TOC component.

::page-toc
---
title: "On this page"
max-depth: 2
---
::