# Page configuration

Individual .md pages can be configured using the metadata section added to the top of the page.

sample.md
---
label: Sample
layout: page
order: 100
---
# Sample page

This is a sample page demonstrating page metadata.

# Separate .yml configuration

If you would prefer to keep the page metadata separated and placed outside of the .md content page, the options can be moved into a paired .yml file.

For instance, sample.md would need a matching sample.yml file. The separate .yml file must have the exact same filename as the matching .md page.

Both .yml and .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.md
# Sample page

This is a sample page demonstrating page metadata.
sample.yml
label: Sample
layout: page
order: 100

If you add a config to both locations, the page metadata take precedence.

See Folder configuration for details on how to configure a folder.


# description

A custom description of the current page.

description: This is a custom description for this page

# expanded

Determines whether this folder should be expanded in the tree navigation on initial page load. Default is false.

Set to true to expand the folder node in the navigation.

expanded: true

The expanded option only applies to folders when configured within an index.yml folder configuration file.

Setting expanded: true within the metadata of an .md page or the paired .yml file will be ignored.


# hidden

Hides the current page in the navigation and from the search results. Default is false.

Set to true to hide.

hidden: true

# icon

Custom icon for the navigation node of the current page. Default is null.

Options include using an Octicon name, Emoji shortcode, <svg> element, or a path to an image file.

Octicon
icon: rocket
Emoji shortcode
icon: ":rocket:"
SVG element
icon: "<svg>...</svg>"
Path
icon: "../static/rocket.png"

# image

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.

# Local path

Configure a path to a local file stored within the project.

image: ../static/feature-image1.jpg

# External image

Configure a URL to any image hosted elsewhere.

image: https://example.com/static/feature-image1.jpg

# label

Custom label for the navigation node for the current page. Default is null.

label: Custom label

# layout

The layout for the page. Default is default.

Supported values: default, central, page, and blog.

Layout Description
default The default layout for all .md pages. The page is added to the main navigation.
page Similar to default layout, but is not added to the main navigation.
central A page with no left or right sidebar columns.
blog A blog page layout. Blog pages are not added to the main navigation and include blog specific < Newer and Older > navigation buttons at the bottom of each blog page.
layout: page

# order

A custom stack order within the navigation.

Options can include:

  • A number such as 100 or -100
  • Any string value that will be slotted into the A -> Z alpha ordering of all navigation nodes
  • A SemVer value such as v2.0

In order of precedence, the order would be applied with the following priority:

number (high)
alpha (a)
neutral (by alpha)
alpha (z)
vSemver (newest)
vSemver (oldest)
number (low)

# 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{semver}

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 and mixed with other alpha values would be grouped at the end of

alpha
bravo
yankee
zulu
v3.0
v2.1-beta
v2.0
v1.0
v1.0-beta
v1.0-alpha

# route

A custom URL path for this page or folder which overrides the default path generated by Retype.

sample.md
---
route: /custom/path
---
# My page title

Some content here.

A custom route allows the folder and file structure to remain unchanged, but allowing the final URL's to be customized.

Configuring the 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 /tutorial/publish-to-github-pages/.

/guide/2021-06-25-publishing-to-github-pages.md
---
route: /tutorial/publish-to-github-pages/
---
# Publishing to GitHub Pages

If a custom route is configured on a folder, or on a readme.md or index.md page within the folder, or on an index.yml file within the folder, that custom route is assumed to be the base route for all pages within that folder.

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 /tutorials/.

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 /tutorials/configuration/.

Folder structure
|-- /guides
    |-- readme.md
    |-- configuration.md
/guides/readme.md
---
route: /tutorials
---
# Tutorials
File path Old URL New URL
/guides/readme.md /guides /tutorials
/guides/configuration.md /guides/configuration /tutorials/configuration

# tags

A list of tags can be added to the metadata at the top of each .md page you would like to tag.

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.

Sample tags configuration
---
tags: [guide]
---
# Page title

Some content here.

Multiple tags can be added to the list by separating each with a comma ,.

Sample list of tags
---
tags: [guide, config options, installation]
---
# Page title

Some content here.

A list style syntax is also supported for tags:

Sample tags list
---
tags:
    - guide
    - config options
    - installation
---

# title

The 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 title. As a general rule, the actual content of your page should not be configured in the page metadata.

The 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 <h1>Page Title</h1>.

For example, the sample above should ideally be written as the following instead of using a title config.

# Getting Started

Some content here.