What is YAML Frontmatter in Markdown?

YAML frontmatter is a standardized convention for embedding structured metadata at the beginning of plain-text Markdown documents. Delimited by triple hyphens (---) at the top and bottom, the block is written in YAML (YAML Ain’t Markup Language) syntax.

First introduced to web publishing by static site generators like Jekyll and Middleman, frontmatter has become an essential standard for modern knowledge management tools, documentation engines, and desktop note applications.

Anatomical structure of a frontmatter block

A frontmatter block must begin on the very first line of a file:

---
title: "Q4 Cryptographic Architecture Audit"
date: 2026-10-09
updated: 2026-10-09
tags:
  - security
  - architecture
  - macos
aliases:
  - Crypto Audit 2026
  - Security Review Q4
status: "Finalized"
confidential: true
participants:
  - Marcus Vance
  - Sarah Lin
---

# Q4 Cryptographic Architecture Audit

Document body begins here in standard CommonMark...

Standard properties in personal knowledge management

Several frontmatter keys have achieved broad cross-application standardization:

• tags: A list or array of categorical labels indexing the note.
• aliases: Alternative titles that resolve through [[WikiLink]] autocomplete (e.g., typing [[Crypto Audit 2026]] points to this note).
• date / updated: ISO 8601 timestamps recording document provenance.
• publish: A boolean flag instructing static site generators whether to include the document in public builds.

How Oyma utilizes YAML frontmatter

In Oyma on macOS:

• Meeting notes automatically generate frontmatter containing meeting timestamps, calendar event IDs, attendee lists, and audio duration.
• Frontmatter values are parsed into Oyma‘s local SQLite FTS5 database, enabling fast structured queries (e.g., filtering notes where confidential: true).
• The editor renders frontmatter as an elegant, collapsible Properties card, hiding YAML punctuation while allowing direct point-and-click property management.
• Raw files on your Mac disk remain 100% standard plain text.

Supported YAML data types in note properties

Frontmatter supports multiple native data types that enable structured querying:

• Strings: Plain text titles and categories (status: "Finalized").
• Booleans: Binary flags (archived: false, confidential: true).
• Dates & Times: Standard ISO 8601 timestamps (created: 2026-10-09T14:30:00Z).
• Lists / Sequences: Ordered arrays of tags or attendees (attendees: [Marcus, Sarah]).
• Numbers: Numeric metrics or scores (confidence_score: 0.98).

By maintaining strict YAML data typing, your notes can be processed by command-line utilities (like `yq` or Python scripts) and static site generators without data conversion.