Getting Started

Welcome to YAML Toolkit for Obsidian! This guide will help you understand the basics of manipulating YAML front matter in your Obsidian vault.

What is YAML Front Matter?

YAML front matter is metadata at the top of your Markdown notes, enclosed by ---:

---
title: My Note
tags: [project, active]
status: in-progress
created: 2025-01-01
---

# Note content here

Core Concepts

YAML Toolkit for Obsidian operates on three key concepts:

1. Conditions (File Filtering)

Conditions determine which notes will be affected based on their frontmatter. Enter these in the Find files based on frontmatter field:

status = "draft"

tags contains "project" AND status != "archived"

NOT HAS deadline

2. Actions

Actions specify what changes to make. Scalar operations (single values) don't use FOR, collection operations (arrays/objects) do. Enter these in the Action field:

SET status "active"

FOR tags APPEND "reviewed"

DELETE old_field

Scalar operations: SET, DELETE, RENAME, INCREMENT, DECREMENT (no FOR) Collection operations: FOR array/object operations (FOR required)

3. Rules

The plugin combines your condition and action automatically.

You enter (Rule 1):

• File filter: status = "draft" AND tags exists
• Action field: SET status "ready-for-review"

You enter (Rule 2):

• File filter: status = "draft" AND tags exists
• Action field: SET reviewed_date "2025-11-24T22:10:00"

The plugin executes:

• Each rule: IF condition is true, THEN perform the action

Your First Rule

Let's create a simple rule to add a "reviewed" tag to all notes that don't have it:

1. Open YAML Toolkit for Obsidian from the command palette (Cmd/Ctrl + P)
2. In the Find files based on frontmatter field, enter:

   NOT tags contains "reviewed"

3. In the Action field, enter:

   FOR tags APPEND "reviewed"

4. Click Preview to see which notes will be affected
5. Review the changes
6. Click Apply to execute

Note: You don't type "IF" or "THEN" - the plugin handles that automatically!

Action Syntax

Scalar operations (no FOR):

SET field "value"             # Set field
DELETE old_field              # Delete field
RENAME old TO new             # Rename field
INCREMENT counter 1           # Increment field
DECREMENT counter 1           # Decrement field

Collection operations (FOR required):

FOR tags APPEND "urgent"      # Append to array
FOR tags WHERE $ = "old" REMOVE  # Conditional remove
FOR array SORT BY field       # Sort array
FOR object MERGE {data}       # Merge object

Examples:

SET status "active"
FOR tags APPEND "reviewed"
FOR tasks WHERE status = "pending" SET status "active"

Next Steps

• Learn about file selection criteria
• Explore all available actions
• See examples
• Learn about complex queries