obsidian-frontmatter

name

obsidian-frontmatter

description

Lightweight plugin for managing Obsidian frontmatter properties using functional shell operations. This skill should be used when working with YAML frontmatter in Obsidian markdown files - adding, updating, removing, or validating properties. Works with any Obsidian vault following standard YAML conventions. Supports full YAML including nested structures, arrays, and wikilinks. Uses composable shell functions for single-file or bulk operations without external dependencies.

Obsidian Frontmatter Manager

A lightweight, dependency-free skill for managing YAML frontmatter in Obsidian markdown files. Built with functional programming principles using pure shell tools (awk, no Python/JS dependencies).

Overview

This skill provides a composable toolset for frontmatter operations in Obsidian vaults. It understands generic Obsidian YAML conventions and works across any vault configuration.

Key features:

• ✅ No external dependencies (pure shell: bash, awk)
• ✅ Composable functional design (single operations compose into bulk)
• ✅ Full YAML support (scalars, arrays, nested objects)
• ✅ Wikilink handling (automatic quoting)
• ✅ Unicode support (Korean, emoji, international characters)
• ✅ Parallel bulk operations (4 concurrent processes)
• ✅ Vault-agnostic (works with any Obsidian vault)

Core Operations

The skill follows a functional programming approach with a single core function that composes for bulk operations:

# Core function signature
fm-op <operation> <file> <property> [value] [options]

# Bulk operations through composition
fm-bulk <operation> <property> [value] <file-pattern> [options]

Available Operations

1. get - Extract property value
2. set - Add or update property
3. delete - Remove property
4. validate - Check required properties exist

Usage Examples

Basic Operations

Get property value:

fm-op get "note.md" "tags"
fm-op get "note.md" "title"

Set simple property:

fm-op set "note.md" "title" "My Note"
fm-op set "note.md" "status" "published"
fm-op set "note.md" "rating" "4.5"

Set wikilink (automatically quoted):

fm-op set "note.md" "author" "[[John Doe]]" --quote
fm-op set "note.md" "parent" "[[Parent Page]]" --quote

Set array property:

# Create new array
fm-op set "note.md" "tags" "obsidian" --array

# Append to existing array
fm-op set "note.md" "tags" "tutorial" --array --append
fm-op set "note.md" "tags" "example" --array --append

Delete property:

fm-op delete "note.md" "old_field"
fm-op delete "note.md" "draft"

Validate required properties:

# Check single property
fm-op validate "note.md" title

# Check multiple properties
fm-op validate "note.md" title tags author

List all properties:

fm-list "note.md"

Bulk Operations

Set property across multiple files:

# Publish all content
fm-bulk set publish true "content/**/*.md"

# Add tag to all notes
fm-bulk set tags obsidian "**/*.md" --array --append

# Set status for drafts
fm-bulk set status published "drafts/*.md"

Delete property from multiple files:

# Remove draft status from all files
fm-bulk delete draft "content/**/*.md"

# Clean up old property
fm-bulk delete old_field "**/*.md"

Validate properties across files:

# Check all files have title and tags
fm-bulk validate title "**/*.md" tags

# Validate content files
fm-bulk validate title "content/**/*.md" author publish

Advanced Examples

Add author to literature notes:

fm-bulk set author "[[고범수]]" "30. Zettels/01. Literature Notes/*.md" --quote

Tag all meeting notes:

fm-bulk set tags meeting "10. Time/03. Meeting/**/*.md" --array --append

Publish digital garden articles:

fm-bulk set publish true "40. Digital Garden/Articles/*.md"

Validate project structure:

fm-bulk validate status "10. Time/02. Project/**/*.md" project_type

Obsidian YAML Conventions

This skill follows standard Obsidian YAML conventions:

Frontmatter Structure

• Enclosed by --- delimiters on separate lines
• Must start at first line of document
• Blank line after closing ---

Important Conventions

Wikilinks must be quoted:

# Correct
author: "[[Name]]"

# Incorrect - causes YAML errors
author: [[Name]]

Standard indentation:

# 2 spaces (default)
tags:
  - tag1
  - tag2

Common properties:

• tags - Categorization (array or scalar)
• aliases - Alternative names (array)
• type - Note type
• status - Progress status
• author - Author (often wikilink)
• date_created, date_modified - Timestamps
• publish - Publishing flag
• cssclass - Styling class

Full YAML Support

Scalars:

title: Simple Value
status: draft
published: true
rating: 4.5

Arrays (single-line):

tags: [obsidian, tutorial, example]

Arrays (multi-line):

tags:
  - obsidian
  - tutorial
  - example

Nested objects:

metadata:
  created: 2025-01-27
  author: "[[Name]]"

Unicode support:

title: "한글 제목"
author: "[[고범수]]"
tags: [📝, 🎯, ✅]

For complete conventions, see references/obsidian-yaml-conventions.md.

Advanced Operations

Complex YAML Structures

The skill handles complex YAML patterns:

Multi-line arrays:

# Automatically detects and preserves format
fm-op set "note.md" "aliases" "Alt Name" --array --append

Nested properties:

# Works with nested structures
fm-op get "note.md" "metadata"

Special characters:

# Handles colons, quotes, and special characters
fm-op set "note.md" "title" "Chapter 3: The Beginning" --quote

Formatting Preservation

The skill preserves existing formatting:

• Maintains 2-space indentation
• Keeps array format (single-line vs multi-line)
• Preserves property order
• Retains blank lines and structure

Error Handling

Graceful error handling:

• Creates frontmatter if missing
• Reports malformed YAML
• Validates operations before execution
• Clear error messages

Safe operations:

# Check before bulk update
fm-op validate "note.md" title || echo "Missing title, skipping"
fm-op set "note.md" "status" "published"

Bulk Operations

Patterns for Mass Updates

Using find with fm-op:

# Custom filtering with find
find . -name "*.md" -type f -mtime -7 -exec \
  fm-op set {} updated "$(date +%Y-%m-%d)" \;

# Conditional updates
find . -name "*.md" -type f | while read file; do
  if fm-op validate "$file" title 2>/dev/null; then
    fm-op set "$file" validated true
  fi
done

Using fm-bulk wrapper:

# Standard bulk operations (uses 4 parallel processes)
fm-bulk set tags obsidian "**/*.md" --array --append
fm-bulk delete old_property "**/*.md"
fm-bulk validate title "**/*.md" tags

Performance

Bulk operations use parallel execution:

• 4 concurrent processes by default
• Efficient for large vaults (1000+ files)
• Progress visible during execution

Example timing:

• 100 files: ~2 seconds
• 1000 files: ~15 seconds
• 5000 files: ~60 seconds

Integration with Claude Code

Automatic Triggering

Claude Code automatically uses this skill when:

• Working with Obsidian markdown files
• Adding, updating, or removing frontmatter properties
• Validating note metadata
• Bulk updating vault properties

Complementary Tools

Works alongside:

• Obsidian Linter - For style enforcement
• Dataview - For property queries
• Templater - For template-based property insertion
• Custom plugins - Any plugin using standard YAML

Safe Operations

The skill ensures:

• No data loss during updates
• Preserves existing formatting
• Clear error messages
• Validation before bulk operations

Implementation Details

Technical Architecture

Core technology:

• AWK for YAML parsing (simple structures)
• Perl for complex updates (nested structures)
• Bash for orchestration and composition

Design principles:

• Single function for individual operations
• Composable for bulk operations
• No external dependencies
• Functional programming approach

Edge Cases Handled

• ✅ Files without frontmatter (creates new)
• ✅ Malformed YAML (reports error)
• ✅ Missing properties (creates or returns empty)
• ✅ Special characters (Korean, emoji, colons)
• ✅ Wikilinks (automatic quoting)
• ✅ Multi-line values (preserves format)
• ✅ Nested structures (maintains hierarchy)

Parsing Patterns

For implementation details and parsing techniques, see:

• references/yaml-parsing-patterns.md

Examples by Use Case

Literature Notes

# Add metadata to new literature note
fm-op set "lit-note.md" type "Literature Notes" --quote
fm-op set "lit-note.md" author "[[Paper Author]]" --quote
fm-op set "lit-note.md" source_url "https://example.com/paper.pdf"
fm-op set "lit-note.md" tags reading --array

Project Management

# Initialize project note
fm-op set "project.md" type project --quote
fm-op set "project.md" status todo --quote
fm-op set "project.md" project_type project --quote

# Update all project statuses
fm-bulk set status inprogress "10. Time/02. Project/**/*.md"

Digital Garden

# Prepare articles for publishing
fm-bulk set publish true "40. Digital Garden/Articles/*.md"
fm-bulk set cssclass article "40. Digital Garden/Articles/*.md"
fm-bulk validate title "40. Digital Garden/Articles/*.md" tags author

Bible Study Notes

# Tag sermon notes
fm-bulk set tags sermon "60. Saint/01. Sermon/**/*.md" --array --append
fm-bulk set author "[[Pastor Name]]" "60. Saint/01. Sermon/**/*.md" --quote

Troubleshooting

Common Issues

Wikilink parsing errors:

# Solution: Always use --quote for wikilinks
fm-op set "note.md" "author" "[[Name]]" --quote

Array format:

# Create multi-line array
fm-op set "note.md" "tags" "first" --array
fm-op set "note.md" "tags" "second" --array --append

Validation failures:

# Check what's missing
fm-op validate "note.md" title tags author || echo "Validation failed"
fm-list "note.md"  # List current properties

Debugging

Check property value:

fm-op get "note.md" "property_name"

List all properties:

fm-list "note.md"

Test on single file first:

# Test before bulk operation
fm-op set "test.md" "property" "value"
fm-list "test.md"
# Then apply to all files
fm-bulk set "property" "value" "**/*.md"

Development and Extension

Custom Scripts

Build on core functions:

#!/bin/bash
# custom-update.sh - Add created date to notes

for file in *.md; do
  if ! fm-op get "$file" date_created >/dev/null 2>&1; then
    fm-op set "$file" date_created "$(date +%Y-%m-%d)"
  fi
done

Integration Examples

With git hooks:

# pre-commit hook: validate frontmatter
find . -name "*.md" | while read file; do
  fm-op validate "$file" title tags || exit 1
done

With automation:

# Daily cron: update modified dates
find . -name "*.md" -mtime -1 | while read file; do
  fm-op set "$file" date_modified "$(date +%Y-%m-%d)"
done

References

• Obsidian Documentation: Properties
• YAML Specification
• Obsidian Linter Plugin
• references/obsidian-yaml-conventions.md
• references/yaml-parsing-patterns.md

License

MIT License - Free to use and modify

Support

For issues or questions:

• Check references/ directory for detailed documentation
• Review examples in this file
• Test operations on single files before bulk updates
• Validate YAML syntax after updates