# Obsidian Frontmatter Properties: Complete YAML Metadata Guide

> Learn Obsidian frontmatter properties, the YAML metadata essential for controlling note display, linking, and automation. Unlock Obsidian's full potential with structured key-value pairs.

- Repository: [Steph Ango/obsidian-skills](https://github.com/kepano/obsidian-skills)
- Tags: deep-dive
- Published: 2026-03-24

---

**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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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

```markdown
---
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

```markdown
---
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

```javascript
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

```javascript
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`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-markdown/references/PROPERTIES.md)**: Defines the canonical list of supported frontmatter properties and their data type specifications
- **[`skills/obsidian-bases/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-bases/SKILL.md)**: Documents the `file.properties` abstraction that exposes frontmatter to automation scripts
- **[`skills/obsidian-markdown/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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.