My Definitive Front Matter
With every static site generator, you can write your posts or pages with Markdown or CommonMark files in which you can include some structured metadata called a Front Matter.
When you start building a website with any of these products — I’m most familiar with Jekyll by far —, the default scaffolding will prepare sample posts using front matter keys that it considers as required. From this basic starting point, users will have the liberty to add any additional keys of their liking. Over time, after running many Jekyll projects, I came to rely mostly on the following set:
layout: post id: 61C15587-6353-4F0B-B7EA-5FB936E1B7B2 title: Hey Jude author: Paul McCartney excerpt: >- *Hey Jude* is a song by the English rock band the Beatles that was released as a non-album single in August 1968. image: hey-jude-single.jpg category: Past Masters tags: - 1968 - Julian Lennon - Na na na nananana revisions: "2021-01-18": Fixed typos alert: level: info content: This is one of the greatest songs ever.
I’ll detail each field now, having Jekyll in mind, but I’m pretty sure this can be applied to any static generator.
This is pretty basic. With Jekyll, you can include a default layout in the site configuration but I like to keep it explicit.
This is optional, but if you intend to change URL over time, it can be useful to keep consistent feed since an ID is required by both Atom feeds and JSON feeds.
Titles are important since you don’t want to rely on filenames to get your posts’ names from. Some useful links to get capitalization right:
- in English, I like The Capitalizer;
- in French, I couldn’t find a good tool but this page from an academic in Quebec has a good overview of the rules to respect.
This is optional since it will be relevant only if the website has more than 1
contributor. Also, most plugins allow it to be changed to
authors in case an
article is written by more than 1 person. In case you want to attach rich data
for each author, the Author information section from jekyll-feed’s
README has good tips.
This is optional. By default the first paragraph of the post will be used. But it’s good to keep control over what will probably appear on the home page’s reference to your post or social networks. I like excerpt better than description because it is more specific and explicit.
This is the cover of your post or page. I was using cover for a while before realizing jekyll-feed was using image by default so I converted.
Categories and Tags
As for the author, most plugins and themes will support singular or plural forms of these tags.
What is the difference between the two?
I would say that categories are the paths of the navigation tree for your website (just like folders and subfolders where you would store your files). That’s what would be used to build a breadcrumb.
Tags on the other hand can be whatever and don’t involve any kind of structure for your data.
To put it another way, categories form a relatively rigid tree, while tags form a free-form cloud.
This section was
stolen inspired by the front matter of NSHipster’s articles (see
the source for their
XCTestCase post for instance). When you intend to
keep your content relevant over time, it is very useful to let your users know
you updated your content so the revisions feature, albeit specific, can become super
If you want to feature informative banners, in case you deprecate content, or want to include an update to a post, an alert front matter is probably a better way to go than modifying your content to include extra content (that would probably be HTML to include an alert styling anyway, which you should avoid as much as possible).
No date? No slug?
Unless you intend to post multiple times a day, I would say the date belongs to the filename only, and I don’t see the point of including the date with an additional time in the front matter since it seems to just add clutter to it.
On a similar note, I like that the slug for the URL is also part of the
filename. I don’t see any inconvenience doing so since Git does a pretty good
job at identifying renamings now, and the
id can help you tracking URL that
changed over time so that they don’t get duplicated in feeds.
Any thoughts? Let me know.