Override a page template

Custom page templates is a feature that allows you to create more complex templates for your .md pages.

In the default template you have main content in the left column and Table of Content (TOC) on the right (if it's not disabled by theme config).

But there may be types of pages where you would want to display some additional metadata.

Let's consider a blog post page as an example. On that page except the text of the blog itself you may want to display:

• information about the author
• length of the article
• published date
• related articles or just newer/older articles
• list of search tags
• etc.

Also you need to know how you want to display that additional information. Here's where you can use custom page templates.

A custom page template is a regular react component.

The file that defines that component should be placed within the custom theme structure (@theme/Templates/YourTemplate).

Below is a simplified example of a blog page template:

import React from 'react';
import { Markdown as MarkdownWrapper } from '@redocly/theme/components/Markdown/Markdown';
import { PostInfo } from '../Blog/PostInfo';
export default function BlogPost({ pageProps, children }) {
  return (
    <Wrapper data-component-name="Templates/BlogPost">
      <PostInfo data={pageProps.frontmatter} />
      <MarkdownWrapper>{children}</MarkdownWrapper>
    </Wrapper>
  );
}

You can assign a template in one of two ways:

1. Front matter — set template on an individual Markdown page.
2. markdown.template — map patterns to template paths in the root redocly.yaml file.

In your blog file use template property of frontmatter to apply custom template.

Note: frontmatter can be used to pass any additional data to the template. Please check out the example of blog post page.

---
title: Redocly as Remockly
template: '../@theme/Templates/BlogPost'
author:
  name: Adam Altman
  avatar: https://redocly.com/static/adam-b2e77696e09f69bff10f9bc393f45249.png
date: 05-03-2022
timeToRead: 10 min
sidebar: false
---

## Redocly rebrands as Remockly

The Redocly brand is synonymous with quality API documentation.
And we're so much more than that.

"Redocly does much more than API docs.
We searched the world far and wide for marketing experts and determined the fastest way to communicate the breadth of our offering is to rename the company," said co-founder and CTO Roman Hotsiy.

...

From this example the Redocly as Remockly blog post will use custom template located at @theme/Templates/BlogPost and other data like author, date, timeToRead, etc. will be passed to that template in pageProps.frontmatter property (see example of custom template above).

Use markdown.template in the root redocly.yaml file to assign templates to one or more Markdown files without editing each page.

Each key can target files in three ways:

When multiple patterns match a file, the most specific pattern is applied.

markdown:
  template:
    'blog/**': './@theme/Templates/BlogPost'
    'blog/drafts': './@theme/Templates/Draft'
    'demos/new-api.md': './@theme/Templates/SimpleApi'

In this example:

• Every Markdown file under blog/ uses the BlogPost template.
• Files under blog/drafts/ use the Draft template instead.
• Only demos/new-api.md uses the SimpleApi template.

One column template with metadata above main content

Two columns template with metadata on the right