YAML Frontmatter in Obsidian

Your Obsidian vault is a library of interconnected ideas, but without a catalog system, finding and relating those ideas can become a chore. YAML frontmatter provides that catalog, transforming your notes from isolated text files into a structured, queryable database. By adding simple metadata blocks to your notes, you unlock powerful capabilities for filtering, sorting, and automating your knowledge work, making your entire vault more intelligent and responsive to your needs.

What is YAML Frontmatter and Why It Matters

YAML frontmatter is a block of structured metadata placed at the very top of a Markdown file, enclosed by three hyphens (---) on both sides. It uses YAML (YAML Ain't Markup Language) syntax, a human-readable format for defining key-value pairs. In Obsidian, this isn't just a comment; it's a functional component that plugins and core features can read and act upon.

Think of frontmatter as the standardized label on a filing folder. Without it, every note is a plain manila folder—you must open each one to see its contents. With frontmatter, each folder gets a clear label stating the topic, creation date, related projects, and status. This allows you to manage your notes at a collection level. The primary power of frontmatter is realized through integration with plugins like Dataview, which can query this metadata to generate dynamic lists, tables, and dashboards, turning your passive vault into an active workspace.

Core Syntax and Standard Properties

Writing YAML frontmatter is straightforward. You define properties using a key: value format. The block must be the first thing in your file.

---
title: "The Complete Guide to Habit Formation"
created: 2023-10-26
tags: [psychology, self-improvement, productivity]
status: "in-progress"
---
# Your note content begins here

Keys are case-sensitive. Values can be strings (in quotes if they contain special characters), numbers, dates (in ISO 8601 format like YYYY-MM-DD), or lists (using square brackets []). Obsidian and many community plugins recognize several standard properties by convention:

• title: Overrides the filename for display purposes in graphs and some plugins.
• aliases: Provides alternative names for linking, e.g., aliases: [PKM, Zettelkasten].
• tags: A list of tags that apply to the entire note. While you can use #tags in the note body, frontmatter tags keep them consolidated.
• created / updated: Dates for tracking the note's lifecycle.

Defining these standard properties consistently is the first step toward a searchable vault.

Designing Custom Fields and Schemas

The true flexibility of frontmatter lies in defining your own custom fields. These are any key-value pairs that make sense for your workflow. The key is to design a consistent frontmatter schema—a blueprint—for different types of notes.

For example, a note about a book would have a different schema than a project meeting note. Here’s how you might define them:

Book Note Schema:

---
title: "Atomic Habits"
author: "James Clear"
year: 2018
topics: [habits, systems, incrementalism]
read_status: "completed"
rating: 9
summary: "A practical guide to building good habits and breaking bad ones through small, atomic changes."
---

Project Meeting Note Schema:

---
meeting_date: 2023-10-26
project: "Website Redesign"
attendees: [Alice, Bob, Charlie]
decisions: ["Approved new homepage mockup", "Pushed launch date to Q2"]
action_items: ["Bob to finalize copy", "Alice to contact dev team"]
next_meeting: 2023-11-02
---

By deciding on a schema for each note type, you ensure data consistency. This consistency is what makes advanced querying possible, as you can reliably filter for all book notes where rating is greater than 8 or all project notes where attendees includes "Alice".

Integrating with Dataview for Dynamic Querying

Frontmatter's data is inert without a way to read it. The Dataview plugin is the engine that brings it to life. Dataview uses a query language (or JavaScript) to create dynamic views of your notes based on their frontmatter and content.

A simple Dataview query in a note might look like this:

LIST FROM #book WHERE read_status = "completed" AND rating >= 8 SORT rating DESC

This query would automatically generate a bulleted list of all notes tagged #book (or with tags: [book] in frontmatter) that are marked as completed and have a rating of 8 or higher, sorted from highest to lowest rating. You can create tables, task lists, and calendars. This turns a note into a live dashboard that updates as you add or edit notes in your vault. The integration is seamless: define properties in frontmatter, then use Dataview to collect, filter, and display notes anywhere.

Leveraging Templates and Plugins for Automation

Manually typing the same frontmatter structure is tedious. Obsidian Templates are the solution. You can create a template file for each of your schemas (e.g., Template-Book Note.md) that contains the pre-formatted YAML block with placeholder fields. Using the core Templates plugin or community plugins like Templater, you can insert these schemas into new notes with a hotkey, ensuring consistency from the start.

Plugins extend frontmatter's functionality further:

• QuickAdd: Can prompt you for values (like rating or project) when creating a note, auto-populating the frontmatter.
• Linter: Can automatically format and standardize your frontmatter across your entire vault, fixing indentation, date formats, and missing fields.
• Calendar: Can use the created date to display notes on a calendar view.
• Various Graph plugins: Can use frontmatter fields like status or topic to color-code and filter your global and local graph views.

The ecosystem turns frontmatter from a static data block into a dynamic control panel for your vault.

Common Pitfalls

1. Inconsistent YAML Syntax: The most common error is invalid YAML, which causes the entire block to be ignored. Ensure proper indentation (using spaces, not tabs), that colons follow keys immediately, and that lists are formatted correctly. A YAML validator can help troubleshoot.

• Correction: Use Obsidian Linter or paste your frontmatter into an online YAML validator to check for syntax errors. Pay special attention to multi-line strings, which require specific | or > syntax.

1. Over-Engineering Your Schema: It's easy to get excited and create 20 custom fields for every note type. This leads to blank fields and maintenance fatigue.

• Correction: Start minimal. Add fields only when you have a clear use case for querying or sorting by that information. Your schema should evolve with your actual needs.

1. Mixing Frontmatter and Inline Tags Inefficiently: Using #tags in the body and a tags: list in frontmatter can lead to confusion and broken queries.

• Correction: Establish a clear policy. A good rule is to use frontmatter tags: for broad, categorical tags (e.g., book, person, project) and inline #tags for specific, contextual concepts mentioned within the note's prose.

1. Forgetting That Frontmatter is Part of the Note: When you search in Obsidian (Ctrl+F/Cmd+F), the search includes the YAML block. This can cause unexpected search results if you have common words as values.

• Correction: Be mindful of this when performing full-text searches. Use Dataview queries for searching metadata, as they are more precise for that purpose.

Summary

• YAML frontmatter is a metadata block enclosed in --- that adds structured, queryable data to your Obsidian notes, acting as a catalog system for your vault.
• Design consistent schemas using both standard properties (like tags, aliases) and custom fields (like rating, project) tailored to different note types (books, people, projects).
• The Dataview plugin unlocks the potential of frontmatter, allowing you to write queries that generate dynamic lists, tables, and dashboards based on your note metadata.
• Automate and maintain consistency by using Templates to insert pre-defined frontmatter schemas and plugins like Linter and QuickAdd to streamline your workflow.
• Avoid common issues by validating YAML syntax, starting with a minimal schema, and clearly separating the use of frontmatter tags from inline tags.