Last updated

Front matter configuration options

By adding front matter to a Markdown page, you can override per-page configuration options. Front matter must be at the beginning of a Markdown file, in valid YAML format between triple-dashed lines (---).

There are two types of front matter options:

  • Options that are only available in a page's front matter
  • Options that can override global configurations in the redocly.yaml file

Options in front matter only

The following front matter options can configure pages but are not available in the global configuration (redocly.yaml):

OptionTypeDescription
slugstring or [string]The URL path or "slug" to use for this page, instead of the default path created from the folder and file names. You can add multiple slugs for a single page. Use this option to have content showing at one or more custom URLs. The slug can contain multiple segments. For example, '/custom-pages/page-1'.
templatestringPath to a custom template for the Markdown page. Do not include file extensions. Use a relative path for templates defined locally and an absolute path for templates from a node module. See Override a page template for more information on how to add and use a custom page template.
sidebarstringPath to the sidebars.yaml file to display as the sidebar for the Markdown page.
excludeFromSearchbooleanSet to true to exclude the page from search. Default value: false

Options that override project configuration

The following options are available in front matter and redocly.yaml. When present in both, the front matter option overrides the global configuration.

OptionTypeDescription
codeSnippetobjectConfigure the controls displayed in a page's code snippet, such as copy, report, expand, and collapse.
breadcrumbsobjectToggle the appearance of a page's breadcrumbs or prefix them with a custom link.
markdownobjectCustomize the behavior and appearance of certain elements that render on a page. Works with last updated, table of contents, and edit page.
seoobjectConfigure the SEO information inside a page's <head> element.
navbarobjectToggle whether a navbar is displayed on a page using the hide option, which is the only navbar option that supports front matter overrides.
footerobjectToggle whether a footer is displayed on a page using the hide option, which is the only footer option that supports front matter overrides.
colorModeobjectToggle whether a page displays the color mode switcher using the hide option.
feedbackobjectCustomize or hide the feedback sentiment form that appears at the bottom of a page using the feedback option.

Examples

The options in this example configure a page in the following ways:

  • Adds two interchangeable prefixes to the page's URL: /pricing and /subscribe.
  • Uses a custom page template for blog posts.
  • Hides the color mode switcher.
---
slug: 
  - /pricing
  - /subscribe
template: '@theme/Templates/BlogPost'
colorMode:
  hide: true
---

The options in this example configure a page in the following ways:

  • Prevents the page from being indexed by search engines.
  • Hides the report button on code snippets.
  • Configures the table of contents to only include header links usp to h2.
  • Prepends a "Home" link onto page breadcrumbs.
seo:
  meta:
    - name: robots
      content: noindex
codeSnippet:
  report:
    hide: true
markdown:
  toc:
    depth: 2
breadcrumbs:
  prefixItems:
    - page: index.page.tsx
      label: Home
      labelTranslationKey: home.title

We recommend using redocly.yaml for the majority of your project configuration and only using front matter configuration when there's a specific need.

Resources