Pages in Orchid are configured in a similar way to most other Static Site Generators, using Front Matter. Front Matter is typically as a block of YAML between pairs of triple-dashed lines, but other configuration formats are also supported (described below). Orchid also extends page configuration with Archetypes, which allow common configurations for pages to be shared and controlled from a centralized location.

See Also:

Edit this page

Front Matter


Front Matter allows you to customize your Pages individually, adding components or menus to just that page, changing the layout, or using configurations specific to the plugin it came from. The Front Matter is optional, but if used, it must be the first thing in the file. Front Matter can use any of Orchid's parser languages, but YAML is the most common, and comes between pairs of triple dashed lines, which is removed from the actual page output. Here's an example, which is the actual Front Matter of this current page:

---
title: Page Configuration
customItems:
    - 'Item One'
    - 'Item Two'
    - 'Item Three'
---

Front Matter can use different languages in two ways: by specifying the language's extension after the first set of dashes, or by using "fences" for that languages. As an example, TOML uses +++ instead of ---, and JSON uses ;;;. The following blocks of TOML Front Matter are equivalent to the YAML Front Matter block above:

---toml
title = "Page Configuration"
customItems = [
  "Item One",
  "Item Two",
  "Item Three"
]
---

+++
title = "Page Configuration"
customItems = [
  "Item One",
  "Item Two",
  "Item Three"
]
+++

The data defined in Front Matter is then included into the page, and can be accessed as template variables anywhere on the page, including components, layouts, included templates, or pre-rendered into the page content. As an example, the following are all rendered dynamically based on this page's Front Matter, shown above:

title: Page Configuration

customItems:

  • Item One

  • Item Two

  • Item Three

Archetypes


Most pages have configurations that are intended to be the same across all pages of that type. Front Matter allows you to customize the data for that single page, and some other Static Site Generators offer capabilities for generating new pages with that common format already set up, but ultimately they offer no guarantee that all pages of a certain type always share the same options. This is where Orchid's Archetypes come in handy, and really begin to show the power and flexibility that Orchid offers with its options management.

Archetypes inject data from a common source into each Page matching that Archetype, with that common source typically being your config.yml. These additional options are then merged with the page's Front Matter options (with options in the Front Matter taking precedence over the Archetypal options). Certain data types may even have multiple Archetypes, giving you hierarchical control over your page configuration.

As an example, I have the following snippet in this site's config.yml:

allPages:
  layout: single

wiki:
  wikiPages:
    layout: geopattern2

The resulting layout for this page is geopattern2.

This page was created by the Wiki plugin, which decided that there exists a wikiPages archetype for all Wiki pages. So I can set the layout for every page in the Wiki from a single location in config.yml, instead of having to copy the layout option into every Wiki source page. But the page also belongs to the allPages Archetype, and will inherit those properties as well. Archetypes are hierarchical, and in this case the wikiPages Archetype will take precedence over allPages in the case that both define the same property.

And best of all, since all pages read from one location, it makes it trivial to change the layout across the theme, since I only have to change it once to see it reflected everywhere. The same is true for configuring page menus, components, draft status, or any other option.

It is worth noting that there is fundamentally no difference with whether the data came from Front Matter or from the Archetype. When options are loaded into the Page, it is completely transparent from which source it came, so you can simply work with the data without worrying that you've missed the Archetypes.