.md pages can be configured using the metadata section added to the top of the page.
--- label: Sample layout: page order: 100 --- # Sample page This is a sample page demonstrating page metadata.
If you would prefer to keep the page metadata separated and placed outside of the
.md content page, the config can be moved into a paired
sample.md would need a matching
sample.yml file. The separate
.yml file must have the exact same filename as its paired
.yaml extensions are supported.
Adding your configs into the top metadata section of a
.md page, or into a separate
.yml file is just a matter of preference. Both techniques produce the same result.
# Sample page This is a sample page demonstrating page metadata.
label: Sample layout: page order: 100
If you add configs to both locations, the page metadata take precedence, even if they are different configs.
If you add one or more configs to a
.md page, Retype will not look for nor read the separate
.yml file. Just use one or the other, but not both.
See folder configuration for details on how to configure a folder.
The configuration name
authors is also supported. The name
authors is an alias of
author and both can be used interchangeably.
The author or multiple authors of this page.
--- author: Frank ---
--- author: firstname.lastname@example.org ---
An author object can also be configured with specific values for the
author config is very flexible and can accept one or more author configurations and even a list of mixed types. The following sample demonstrates adding a list of authors. Two authors are added by name and a third is added only by their email address.
--- authors: [Frank, Annette Jones, email@example.com] ---
Mixed author types are also permitted, including adding a list of authors by name, email, or author configuration objects.
--- # Mix of author types authors: - name: Frank Esposito email: firstname.lastname@example.org link: https://twitter.com/frank avatar: https://example.com/frank.jpg - Annette Jones - email@example.com ---
Possible options for the
--- author: name: Frank Esposito avatar: https://example.com/frank.jpg # custom avatar takes precedence ---
--- author: email: firstname.lastname@example.org ---
--- author: link: https://twitter.com/frank # custom link take precedence ---
--- author: name: Frank Esposito ---
The configuration name
categories is also supported. The name
categories is an alias of
category and both can be used interchangeably.
A category for this page.
category or a list of
categories can be configured in each
.md page you would like to categorize.
category is meant to be a broad grouping of content, where
All of the following are acceptable techniques for configuring a single
category or multiple
--- category: news categories: news category: [news, general] categories: [news, general] category: - news - general categories: - news - general ---
category is configured in the page metadata, the category is added to the top of the page under the main title.
Individual category summary pages will be automatically generated by Retype at
<url>/categories/<category>, plus an additional
<url>/categories index page which lists all categories in the project.
A custom publish date for this page.
date is configured, Retype will add the Published date to the top of the page, just under the main title.
The date must be provided in the
yyyy-mm-dd ISO format or
yyyy-mm-ddThh:mm if you want to include a date and a time.
date: 2020-11-25 # November 25, 2020 date: 2020-11-25T15:30 # November 25, 2020 at 15:30 (3:30 PM)
date is used by Retype to order blog pages. Newer blog pages are ordered first.
A custom description of the current page.
description: This is a custom description for this page
Determines whether this folder should be expanded in the tree navigation on initial page load. Default is
true to expand the folder node in the navigation.
expanded option only applies to folders when configured within an
index.yml folder configuration file.
expanded: true within the metadata of an
.md page or the paired
.yml file will be ignored.
Custom icon for the navigation node of the current page. Default is
Options include using an Octicon name, Emoji shortcode,
<svg> element, or a path to an image file.
By default, Retype will try to find the first image on the page and use that image as the feature image to highlight when creating a summary of the page.
You can customize the feature image by setting the
image config to any local path or external image hosted elsewhere.
Configure a path to a local file stored within the project.
Configure a URL to any image hosted elsewhere.
Custom label for the navigation node for the current page. Default is
label: Custom label
The layout for the page. Default is
||The default layout for all
||A page with no left or right sidebar columns.|
||A blog page layout. Blog pages are not added to the main navigation and include blog specific
A custom stack order for this page within the left side-bar tree navigation.
Options can include:
- A number such as
- Any string value that will be slotted into the
A -> Zalpha ordering of all navigation nodes
- A SemVer value such as
order is set with a number, a larger positive number will give more weight or priority to that page and Retype will bubble up that page in the navigation. For instance, a page configured with
order: 100 will be higher in the navigation than a page configured with
Similarily, a page configured with
order: -100 will be lower in the navigation than a page configured with
order: -10 or any page where no
order is set.
The position of folders within the navigation can be ordered as well using the same
order technique, the only difference that folders are always pinned to the top of their
In order of precedence, the
order of a page in the navigation would be determined with the following priority:
||A larger positive number gets more weight or priority and is pushed higher in the navigation. Largest number at the top. Example:
||A negative number gets less weight or priority and is pushed to the bottom of the navigation. Setting the
By default, the home page of the website has an order of
10000. To add a page in the navigation just above the home page, set a value of
order: 10001 or greater. To add a page in the navigation just below the home page, set a value of
order: 9999 or lower. To move the home page to the bottom of the navigation, set a negative value, such as
Order by number
Larger number = order higher in the stack.
No order number or
0 = order by alpha
Smaller number = order lower in the stack.
If multiple pages have the same
order number, secondary ordering in that cluster is by alpha.
+ 0 -
Order by alpha
Order values by alpha.
a = higher
z = lower
Alpha Bravo Charlie Zulu
Order by `v
Order by semver with latest release at the top
v5.0.1 v5 v4.0 v3.1 v3.0 v2.0 v1.0
Items prefixed with
v would be grouped below the alpha ordered items.
alpha bravo yankee zulu v3.0 v2.1-beta v2.0 v1.0 v1.0-beta v1.0-alpha
Redirect requests for this page to another location.
redirect can be set to another page within this project, or an external link.
For example, you have an existing
setup.md page and you want to move the content to
getting-started.md, but other websites might still be linking to your old
example.com/setup/ page and you want to ensure those links still work. You would then set the following
redirect page config in
setup.md to redirect to
--- redirect: getting-started.md --- # Setup
Retype will automaticially handle any incoming
example.com/setup requests and redirect to the new
Retype is also smart enough to scan your project for any
setup.md links and replace those with a link directly to
A custom URL path for this page or folder which overrides the default path generated by Retype.
--- route: /custom/path --- # My page title Some content here.
route allows the folder and file structure to remain unchanged, but allowing the final URL's to be customized.
route is an excellent solution when moving to Retype from another solution and you would like to maintain existing public URL's, but would prefer to re-organize your
.md content files into a new structure. A custom
route allows for a clean disconnect of the page path from the final published URL path.
In the following sample, the generated URL by Retype would be
/guide/2021-06-25-publishing-to-github-pages/, but we override with a custom route which will publish the page to
--- route: /tutorial/publish-to-github-pages/ --- # Publishing to GitHub Pages
If a custom
route is configured on a folder, or on a
index.md page within the folder, or on an
The following scenario demonstrates a basic scenario where we want to configure the pages within the
/guides/ folder to be served from the custom URL location of
To accomplish this goal, configure the
route on the
readme.md, then all other pages within the same folder will adjust as well. The
configuration.md page will now be served from
|-- /guides |-- readme.md |-- configuration.md
--- route: /tutorials --- # Tutorials
|File path||Old URL||New URL|
A list of tags can be added to the metadata at the top of each
.md page you would like to tag.
tags are meant to describe specific details of the content in that page. Tags are similar to
category is meant to describe be a broad grouping of content. A page can belong to multiple (zero to many) categories and have multiple (zero to many) tags.
If tags are configured in the page metadata, a list of tag links are added to the bottom of the page. See the bottom of this page for a working sample.
Individual tag summary pages will be automatically generated by Retype at
<url>/tags/<tag>, plus an additional
<url>/tags index page which lists all tags and their count used within the project.
--- tags: [guide] --- # Page title Some content here.
Multiple tags can be added to the list by separating each with a comma
--- tags: [guide, config options, installation] --- # Page title Some content here.
A list style syntax is also supported for
--- tags: - guide - config options - installation ---
Templating can be disabled on a per-page basis by setting
templating: false in the page metadata.
--- templating: false ---
title config instructs Retype to add a primary
# Page Title to your page, but it is recommended to manually add a
# Page Title to each of your pages, instead of setting a
As a general rule, the actual content of your page should not be configured in the page metadata.
title is primarily used to support backwards compatibiity with the
.md content style from other older legacy static site generator applications.
The following sample demonstrates setting the
title config instead of explicitly using a
# Page Title to your page.
--- title: Getting Started --- Some content here.
Try to avoid using the
title config. Please add a real page
# Page Title to your document. The
# Page Title will be rendered in HTML as
For example, the sample above should ideally be written as the following instead of using a
# Getting Started Some content here.