What is YAML frontmatter in Markdown?

YAML frontmatter is a block of key-value metadata located at the very top of a Markdown document, enclosed between triple hyphens (`---`). It allows attaching structured properties like dates, authors, tags, and aliases to plain text files.

Where must YAML frontmatter be located in a file?

YAML frontmatter MUST begin on line 1, character 1 of the document. Any preceding whitespace, comments, or blank lines will cause parsers to treat the block as a standard horizontal rule rather than metadata.

How are tags and aliases defined in frontmatter for Obsidian and Oyma?

Tags can be defined as an array (`tags: [meeting, engineering]`) or a list (`tags: - meeting`). Aliases (`aliases: [Weekly Standup, Eng Huddle]`) allow Oyma and Obsidian to link to the note under multiple alternative names.

How does Oyma display frontmatter in the editor?

Oyma parses YAML frontmatter into a clean, collapsible Properties card at the top of the note, with native type-aware controls for dates, checkboxes, tags, and lists.

Markdown YAML Frontmatter: Metadata Syntax Guide

Primary SyntaxObsidian Flavored Markdown

---
title: "Note Title"
tags: [research, ai]
status: in-progress
updated: 2026-10-09
---

YAML frontmatter bridges the gap between unstructured, human-readable prose and structured, machine-queryable data.

Originally popularized by static site generators like Jekyll and Hugo to define page titles, publication dates, and templates, YAML frontmatter is now a cornerstone of modern personal knowledge management in Oyma and Obsidian.

By storing metadata directly inside the .md file, frontmatter ensures your tags, aliases, dates, and custom schemas travel everywhere with the document without requiring an external database.

Frontmatter syntax rules

YAML frontmatter must adhere to strict structural constraints:

Line 1 position: The opening fence (---) must appear on the very first line of the file. No preceding empty lines, spaces, or characters are allowed.
Closing fence: The block must terminate with another line containing three hyphens (---).
Valid YAML syntax: Everything between the fences must be valid YAML (YAML Ain’t Markup Language) syntax.

---
title: "Architecture Decision Record: Local Whisper"
date: 2026-10-09
author: "Alex Rivera"
status: approved
tags:
  - architecture
  - security
  - macos
---

Common frontmatter data types

YAML supports multiple primitive and compound data types:

Strings, numbers, and booleans

---
project: "Oyma macOS Desktop"
revision: 4
confidential: true
confidence_score: 0.98
---

Note on strings: Strings containing colons, quotes, or special characters should be wrapped in double quotation marks (title: "Meeting: Q4 Strategy Review").

Lists and arrays

Lists can be formatted as bullet items or inline comma-separated arrays:

---
# Bullet list format
attendees:
  - Alex Rivera
  - Jordan Lee
  - Taylor Kim

# Inline array format
platforms: [macOS, Apple Silicon]
---

Dates and timestamps

Dates formatted in ISO 8601 (YYYY-MM-DD) are automatically recognized as dates by Oyma:

---
created: 2026-10-09
updated: 2026-10-09T14:30:00Z
---

Obsidian and Oyma special properties

Several frontmatter keys possess special semantic meaning in knowledge management:

1. `tags` (Global taxonomy)

Tags defined in frontmatter are automatically indexed alongside inline #tags across your entire vault:

---
tags: [meeting, client/acme, architecture]
---

2. `aliases` (Alternative titles)

Aliases allow linking to the note under multiple names. If a note titled 2026-10-09-Standup.md has the alias Friday Standup, typing [[Friday Standup]] will automatically connect to that note:

---
aliases:
  - Friday Standup
  - Engineering Alignment
---

3. `cssclasses` (Custom styling)

Allows applying specific CSS styling classes to the note container.

Best practices and common pitfalls

Beware of unquoted colons: In YAML, a colon followed by a space indicates a key-value mapping. Writing notes: Tags: [project] will throw a syntax error. Always quote strings with colons: notes: "Tags: [project]".
Use consistent indentation: Use two spaces for indentation. Never use tabs inside YAML frontmatter.
Avoid blank lines before frontmatter: Never place an empty line before the opening ---.

YAML frontmatter in Oyma on macOS

In Oyma:

Frontmatter renders as an elegant Properties card at the head of each note.
Tags display as clickable pill badges.
Dates render with native macOS date pickers.
In raw source mode, the frontmatter remains standard, clean YAML text on your Mac disk, fully compatible with Obsidian, Git, and automated terminal scripts.

Frequently asked questions

What is YAML frontmatter in Markdown?: YAML frontmatter is a block of key-value metadata located at the very top of a Markdown document, enclosed between triple hyphens (`---`). It allows attaching structured properties like dates, authors, tags, and aliases to plain text files.
Where must YAML frontmatter be located in a file?: YAML frontmatter MUST begin on line 1, character 1 of the document. Any preceding whitespace, comments, or blank lines will cause parsers to treat the block as a standard horizontal rule rather than metadata.
How are tags and aliases defined in frontmatter for Obsidian and Oyma?: Tags can be defined as an array (`tags: [meeting, engineering]`) or a list (`tags: - meeting`). Aliases (`aliases: [Weekly Standup, Eng Huddle]`) allow Oyma and Obsidian to link to the note under multiple alternative names.
How does Oyma display frontmatter in the editor?: Oyma parses YAML frontmatter into a clean, collapsible Properties card at the top of the note, with native type-aware controls for dates, checkboxes, tags, and lists.