frontmatter

From IndieWeb


frontmatter is a common way to include metadata in plain text. Currently the most seen method is including YAML in front of Markdown content, but some document formats offer built-in support for front matter.

Support

  • most static generators support a variety of front matter; this is most commonly YAML, but some accept TOML or JSON.
  • Github displays front matter in Markdown files in a table: Hugo example

IndieWeb Examples

Aaron Parecki

p3k stores all posts as files on disk with frontmatter that contains the metadata for the post, and the post content below. p3k#File_Format

The top-level properties of the frontmatter are mostly proprietary to p3k, and then there is a properties object that contains microformats2 vocabulary values for the post, such as category, syndication and more.

---
published: "2017-04-15T18:23:00-07:00"
type: entry
content-type: text/plain
client_id: https://ownyourgram.com
properties:
  category: indieweb
  location:
    type:
    - h-card
    properties:
      name: Migration Brewing Company
      latitude: 45.526300
      longitude: -122.636451
      locality: Portland
      region: Oregon
      country-name: USA
  syndication: https://www.instagram.com/p/BS7XoRCANxF/
  photo: photo.jpg
  p3k-channel:
  - photos
  - primary
...

Scheming. #indieweb


Brian Tremblay

Brian Tremblay's personal website stores posts in markdown files with front matter. Some of the front matter items map to microformats, and thus use microformats names for ease of understanding:


---
title: Fern Valley
location:
    name: U.S. National Arboretum
    adr:
        locality: Washington
        region: D.C.
...
---

...

Software Examples

asciidoc

asciidoc has a built-in support for metadata. While this metadata is usually minimal, it is OK to extend it with custom variables. It does not seem to support structured data, making it's use a little limited, but since it's part of the format, it's not as alien as the more common methods.

AsciiDoc User Guide
===================
Stuart Rackham <srackham@gmail.com>
:Author Initials: SJR
:toc:
:icons:
:numbered:
:website: http://asciidoc.org/

Jekyll

---
layout: post
title: Blogging Like a Hacker
permalink: https://domain.com/post
category: Meta
excerpt: Hello World!
---


Hugo

Hugo supports YAML, TOML, and JSON, but they need to be separated by different separators. This is a YAML example.

---
title: "spf13-vim 3.0 release and new website"
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
lastmod: 2015-12-23
date: "2012-04-06"
categories:
  - "Development"
  - "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---


Grav

---
title: Title of my Page
slug: my-page-slug
menu: My Page
date: 01/01/2014 3:14pm
published: true
redirect: '/some/custom/route'
template: custom
taxonomy:
    category: blog
    tag: [sample, demo, grav]
routes:
  default: '/my/example/page'
  canonical: '/canonical/url/alias'
  aliases:
    - '/some/other/route'
    - '/can-be-any-valid-slug'
author:
    name: Sandy Johnson
    twitter: @sandyjohnson
    bio: Sandy is a freelance journalist and author of several publications on open source CMS platforms.
---


Obsidian

Obsidian calls its frontmatter "properties". These can be written in YAML or JSON format, and can be used as a key-value store for page metadata that can be referenced by custom plugins. This includes tags.

While an unlimited number of any arbitrary metadata names and values can be added, Obsidian contains special support for the following default defined properties:

---
tags:
  - tag one
  - tag two
aliases:
  - Alternate page name one
  - Alternate page name two
cssclass: class-name-to-apply-to-text
---

This metadata can be searched in Obsidian. For example, a search for [status:Deprecated] will return all pages where the frontmatter property status has been set to Deprecated.


Pelican

Pelican is not following the usual method: it does not have the common separators.

reStructuredText

My super title
##############

:date: 2010-10-03 10:20
:modified: 2010-10-04 18:40
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:authors: Alexis Metaireau, Conan Doyle
:summary: Short version for index and feeds

Markdown

Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds


Criticism

No common set of basic variables

None of the current static generators share the same keywords or syntax for even the most common variables, such as author, tags, publish date; with the exception of "title", though the case might vary here as well. (Title vs title ) - 2016-08-19 petermolnar


Most parsers are not aware of it

Since it's an alien format inside another format (YAML in Markdown most commonly ), therefore regular Markdown parsers are unaware of it and thus it will not be parsed accordingly. pandoc is an exception. - 2016-08-19 petermolnar

See Also