Frontmatter
Frontmatter is hidden metadata that every page of content needs. Sheriff looks here for valuable information that helps it determine the proper way to build each page. Note that blog posts require extra frontmatter fields (see below).
Example
Below you will see an example of frontmatter used in an actual Sheriff docs page. We will go through each item in turn.
^^^^ title: Admonitions & Spoilers author: Sheriff Docs layout: docs meta_kind: tutorial meta_type: docs summary: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers. gloss: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers. aliases: [Andergard, Andergard House, House Andergaard] categories: [Houses, Royal Houses] ^^^^
^^^^ title: Admonitions & Spoilers author: Sheriff Docs layout: docs meta_kind: tutorial meta_type: docs summary: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers. gloss: Styled callout blocks for notes, warnings, strategy, lore, and collapsible spoilers. aliases: [Andergard, Andergard House, House Andergaard] categories: [Houses, Royal Houses] ^^^^
Frontmatter Fences
You will notice something unique about Sheriff's frontmatter. It is bracketed before and after with four carats like this: ^^^^. This tells Sheriff exactly what content is frontmatter, which it will later use to build your page (and it will also not display this information on the final page; it is hidden from view).
^^^^ instead of --- because it turned out to be easier to parse. The other reason is because --- is a horizontal separator in markdown, so we wanted a unique set of characters for this important task.Title
Here is where you put the page title how you want it to be displayed on the final page. This allows you to choose any title you like; Sheriff doesn't try to figure out the title of the page from the file name.
Author
This is where you put the name of the page author. Sheriff uses "Sheriff Docs" and Goblin uses "Goblin Docs" but you may want to put a different author for different content.
Layout
This is where you specify the page layout for that page. This is very important; without it, Sheriff cannot determine what layout to use. If you need to see what layouts are available, look inside your theme's folder:
sheriff-core/themes/{theme}/layouts/Meta Kind and Meta Type
These are mostly decorative. Use these to signal what type of content the page is. Some ideas:
- Meta Kind: docs, wiki, blog, article, etc.
- Meta Type: reference, tutorial, guide, how-to, overview, quickstart, api, changelog, faq, entry, portal, index, post, editorial, review, announcement, opinion, case study, interview, news, definition, concept, walkthrough, comparison, landing, etc.
You can put whatever you like for these, Sheriff will not break.
Summary
This is a one-sentence summary of the content. It is used in search results.
Gloss
This is a one-sentence description or definition that will appear when hovering over a link to the page.
Aliases
If there are any other names for this page, you can list them here and they will automatically redirect to the destination page.
Categories
List any categories this page belongs to and it will show up in that category's directory.
Blog Frontmatter
Blog post frontmatter is the same as regular frontmatter, but with a couple extra fields:
author_avatar: /public/avatars/dan.png
thumb: /public/images/blog/mtg-goblin.png
date: 2015-12-05blog page layout.Author Avatar
This field asks for the relative link to the author avatar in your public directory. Simply upload an image there and link to it here.
Thumb
Like the author avatar, this image will need to exist in your public directory. Link to it in the frontmatter. This image will show up on the blog index.
Date
You must include the date. Do it like we show above and you won't have any problems.
Modules Involved
The following modules are involved in your site's build process:
- Frontier - responsible pulling out all frontmatter and passing it off to be used by other modules