Obsidian Frontmatter Properties: Complete YAML Metadata Guide

Obsidian frontmatter properties are YAML key-value pairs enclosed between --- delimiters at the start of a Markdown file, storing structured metadata that Obsidian and plugins use to control note display, linking behavior, and automation workflows.

Obsidian frontmatter properties provide the foundation for metadata-driven workflows in the kepano/obsidian-skills repository. These properties enable both the core application and community plugins to programmatically read and manipulate note attributes, transforming static Markdown files into dynamic knowledge base entries.

What Are Obsidian Frontmatter Properties?

Obsidian stores metadata for each note in a YAML frontmatter block positioned at the very top of the file, surrounded by --- lines. Each line inside this block defines a property—a key/value pair that Obsidian parses into native JavaScript types to control how the note displays, links to other notes, or triggers automated processes.

The skills/obsidian-markdown/references/PROPERTIES.md file in the repository defines the canonical specification for these properties, documenting supported data types and reserved keywords that receive special handling in the Obsidian interface.

Supported Property Data Types

The repository identifies seven core data types for frontmatter properties:

• Text: Simple string values (e.g., title: Project Alpha)
• Number: Integers or floating-point values (e.g., rating: 4.5)
• Checkbox: Boolean values represented as true or false (e.g., completed: false)
• Date: ISO 8601 dates without time components (e.g., date: 2024-03-15)
• Date & Time: Full ISO 8601 timestamps (e.g., due: 2024-03-15T09:00:00)
• List: Arrays using inline syntax [item, item] or YAML block format with - prefixes
• Links: Obsidian wikilinks enclosed in quotes (e.g., related: "[[Reference Note]]")

Reserved Properties That Control the UI

According to skills/obsidian-markdown/references/PROPERTIES.md, Obsidian reserves specific property names that trigger native UI behaviors:

• tags: Populates the note's tag index, making it searchable and visible in graph view
• aliases: Defines alternate note names that appear in link suggestion pop-ups when creating internal links
• cssclasses: Applies CSS classes to the note in both reading and editing views for custom styling

These properties undergo normalization during parsing—Obsidian automatically converts them into arrays to ensure consistent handling across the interface and plugin ecosystem.

How Obsidian Parses Frontmatter Blocks

When Obsidian opens a note, it executes a four-stage parsing pipeline as implemented in the core application:

1. Detection: The parser identifies the opening --- delimiter and reads until the closing --- line
2. YAML Parsing: The enclosed text parses through a YAML engine, converting keys and values into native JavaScript types (String, Number, Boolean, Date, Array)
3. Normalization: Reserved keys (tags, aliases, cssclasses) transform into standardized arrays regardless of whether they were defined as single values or lists
4. Exposure: The resulting object attaches to the MetadataCache for the file, accessible via metadataCache.getFileCache(file).frontmatter

The obsidian-bases skill further exposes these properties through the file.properties field, abstracting the API for use in automation scripts.

Practical Code Examples

Minimal Frontmatter Block

---
title: Project Alpha
rating: 4.8
completed: false
date: 2024-03-01
due: 2024-03-15T09:00:00
tags: [work, planning]
aliases:
  - Alpha Project
  - Project A
cssclasses: important
related: "[[Reference Note]]"
---

This example demonstrates Text, Number, Checkbox, Date, Date & Time, List, Aliases, CSS classes, and Links all within a single frontmatter block.

Multi-line YAML List Syntax

---
tags:
  - personal
  - health/fitness
  - 2024/goals
---

Tags support letters, numbers (not as the first character), underscores, hyphens, and forward-slashes for hierarchical organization.

Reading Frontmatter via the Obsidian API

const file = app.vault.getAbstractFileByPath('Project Alpha.md');
const cache = app.metadataCache.getFileCache(file);
const front = cache?.frontmatter ?? {};

console.log('Title:', front.title);
console.log('Tags:', front.tags);

This JavaScript snippet retrieves the parsed frontmatter object from the metadata cache and accesses specific properties.

Programmatically Updating Properties

await app.fileManager.processFrontMatter(file, (fm) => {
  fm.completed = true;                    // set checkbox
  fm.rating = (fm.rating ?? 0) + 0.1;      // increment number
});

The processFrontMatter method rewrites the YAML block while preserving the original file formatting and whitespace.

Key Source Files in the Repository

The kepano/obsidian-skills repository contains several authoritative sources for frontmatter implementation:

• skills/obsidian-markdown/references/PROPERTIES.md: Defines the canonical list of supported frontmatter properties and their data type specifications
• skills/obsidian-bases/SKILL.md: Documents the file.properties abstraction that exposes frontmatter to automation scripts
• skills/obsidian-markdown/SKILL.md: Provides overview documentation for Markdown processing, including frontmatter handling conventions

Summary

• Obsidian frontmatter properties use YAML syntax between triple-dash delimiters at the file's start
• Seven data types are supported: Text, Number, Checkbox, Date, Date & Time, List, and Links
• Reserved properties (tags, aliases, cssclasses) receive special normalization and control native UI features
• The parsing pipeline exposes frontmatter via metadataCache.getFileCache(file).frontmatter
• Use app.fileManager.processFrontMatter() to programmatically update values while preserving formatting

Frequently Asked Questions

How do you format Obsidian frontmatter properties correctly?

Obsidian frontmatter properties must reside in a YAML block that starts and ends with triple-dash lines (---). Each property uses key: value syntax, where the value type determines how Obsidian interprets the data—strings require no quotes unless containing special characters, while wikilinks must use double quotes.

What are the reserved property names in Obsidian?

The properties tags, aliases, and cssclasses receive special treatment according to skills/obsidian-markdown/references/PROPERTIES.md. These control the note's tag indexing for search and graph view, alternate names for link suggestions, and CSS class application for custom styling respectively.

How can plugins read frontmatter properties programmatically?

Plugins access frontmatter through the Obsidian API by calling app.metadataCache.getFileCache(file).frontmatter, which returns a JavaScript object containing all parsed key-value pairs. The obsidian-bases skill additionally exposes these via file.properties for streamlined access in automation workflows.

How does Obsidian handle date and time values in frontmatter?

Obsidian parses ISO 8601 dates (e.g., 2024-01-15) into Date objects for the Date type, and full ISO date-time strings (e.g., 2024-01-15T14:30:00) for Date & Time properties. These convert to native JavaScript Date objects during the YAML parsing stage, enabling temporal comparisons and filtering in plugins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}