InkMomentum

Markdown · By Seth ·

YAML front matter in Markdown: give each field a job

YAML front matter is a metadata block that some tools read at the beginning of a Markdown file. It can hold a title, a status, tags, or information used during publishing.

It is a convention supported by particular tools. It is not a promise that every Markdown reader will interpret the block as metadata.

Here is a small example:

---
title: "Project brief"
status: "draft"
tags:
  - writing
  - planning
---

# Project brief

The document begins here.

The lines of three hyphens mark the block’s boundaries in this front-matter convention. Inside the block, YAML describes the values. Your application decides what those values mean.

Start with a question you need answered

“I need metadata” is vague. “I want to find the drafts that are ready for review” gives you a useful reason to add a field.

You might choose status with values such as draft, review, and published. The next question is whether your tool can filter or publish based on those values.

The field alone does not create that behavior. If nothing in your workflow reads it, it is simply information stored at the top of the document.

That can still help a human reader. Just be clear about which job you expect it to do.

Use the fields your tool expects

Different systems use different names and types. One might expect date; another might expect publishedAt. A tag field might accept a list in one system and a string in another.

Before borrowing a front-matter block, check the destination’s requirements. Copying a block from a different publishing tool can give you neatly formatted metadata that your own tool ignores.

The example above illustrates the structure. It is not a universal website configuration.

Quote text when punctuation gets involved

A title such as this is easier to handle deliberately:

title: "Meeting notes: website review"

The colon belongs to the title. Quoting the whole value makes that intention explicit. Quoting intended text can also help avoid accidental interpretation as another data type, although the consuming tool may still apply its own schema.

Use ordinary straight quotation marks in the source. A writing app’s smart-quote replacement can be an unwelcome guest in structured data.

If a quoted value contains quotation marks of its own, check the YAML rules for escaping or choose an appropriate alternative quote style. Don’t keep adding punctuation until the preview happens to work.

Keep indentation consistent

In the example, tags contains a list:

tags:
  - writing
  - planning

The spaces express the relationship between the key and its values. YAML indentation uses spaces, not tabs.

Small metadata blocks are easier to inspect. If the fields become deeply nested and difficult to maintain, ask whether every part is still useful for this document.

Keep decisions and explanations in the body

Metadata is convenient for information you repeatedly sort or process. The document body is often a better place for the reasons behind a decision.

A status can say review. A sentence in the body can explain that the article is waiting for someone to confirm the example. Both pieces of information have a job.

Try one field with a clear use. Confirm that the application reads it correctly. Add the next field when it solves another problem.

A short block you trust is more useful than a long one you keep meaning to clean up.

Sources

Keep exploring

Read the Front matter reference for more examples.

All writing