Shared Configurations give you the freedom to define your own Archetypes and apply them selectively.
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
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 ``.
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
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.
Archetypes are really powerful and provide a clean, opinionated way to structure the common configuration for many pages of your site, but you will likely have certain pages that are related but which do not share any common Archetypes. Shared Configuration is a special Archetype that gives you the freedom to define your own option groups.
Let's start with an example. Say you have a site using Static Page Groups, and want to add an additional menu item to all the "index" pages for each group.
. / (resources root) ├── homepage.md ├── config.yml └── pages/ ├── group-one/ | ├── index.md <-- group-one index page | ├── 1-1.md | └── 1-2.md ├── group-two/ | ├── index.md <-- group-two index page | ├── 2-1.md | └── 2-2.md └── group-three/ ├── index.md <-- group-three index page ├── 3-1.md └── 3-2.md
For the directory structure above, you can see each of the 3 page groups has a similar structure, and each one includes
a file named
index.md, which we want to link to each of the other pages within the group. But the Static Pages plugin
does not provide an Archetype that selects these pages only. The normal solution is to simply copy the configuration you
need to each of those pages, but that can get very difficult to keep in sync amongst all pages over time.
Instead of copying this configuration to each page, we can just add the
from property to each page's Front Matter,
which points to a location within our site config, and now we only need to update the one config to change all pages.
Likewise, adding new pages requires adding only a single line to these new pages.
// group-one/index.md --- from: staticPages.groupIndex --- ...
// group-two/index.md --- from: staticPages.groupIndex --- ...
// group-three/index.md --- from: staticPages.groupIndex --- ...
All of these pages now include the configurations from
staticPages.groupIndex, and we can add the configuration we
want to share to that location in
# config.yml staticPages: groupIndex: # <-- `from: staticPages.groupIndex` points here menu: - type: "pageChildren"
Now, with that set up in
config.yml, the pages that include data
from: staticPages.groupIndex will include the
pageChildren menu item, in addition to the menu items defined in that page's own Front Matter and its other relevant
Shared Configurations take precedence over normal Archetype data, such as
You can also set up more than one SharedConfiguration for a single page by passing a list of pointers rather than single one. If you pass multiple pointers to different shared config locations, the data from pointers later in the list take precedence over those defined earlier.
// group-one/index.md --- from: - staticPages.groupIndex - staticPages.specialIndex # <-- options from here take precedence over those in `staticPages.groupIndex` --- ...