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.yamlfile
Options in front matter only
The following front matter options can configure pages but are not available in the global configuration (redocly.yaml):
| Option | Type | Description |
|---|---|---|
| slug | string 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'. |
| template | string | Path 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. |
| sidebar | string | Path to the sidebars.yaml file to display as the sidebar for the Markdown page. |
| excludeFromSearch | boolean | Set 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.
| Option | Type | Description |
|---|---|---|
| codeSnippet | object | Configure the controls displayed in a page's code snippet, such as copy, report, expand, and collapse. |
| breadcrumbs | object | Toggle the appearance of a page's breadcrumbs or prefix them with a custom link. |
| markdown | object | Customize the behavior and appearance of certain elements that render on a page. Works with last updated, table of contents, and edit page. |
| seo | object | Configure the SEO information inside a page's <head> element. |
| navbar | object | Toggle whether a navbar is displayed on a page using the hide option, which is the only navbar option that supports front matter overrides. |
| footer | object | Toggle whether a footer is displayed on a page using the hide option, which is the only footer option that supports front matter overrides. |
| colorMode | object | Toggle whether a page displays the color mode switcher using the hide option. |
| feedback | object | Customize 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:
/pricingand/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.titleWe recommend using redocly.yaml for the majority of your project configuration and only using front matter configuration when there's a specific need.
Resources
- Override a page template
- Explore the different ways to Configure Redocly using the
redocly.yamlfile.