Markdown Frontmatter Templates Guide

Introduction: Transforming Unstructured Prose into Relational Knowledge

The defining triumph of Markdown is its human-readable simplicity. By using lightweight formatting conventions—hashtags for headers, asterisks for emphasis, brackets for links—Markdown enables writers and engineers to craft rich technical prose without the cognitive overhead of XML tags or binary document processors. However, as personal knowledge management (PKM) vaults grow to encompass thousands of documents, an acute architectural tension emerges: how do you query, filter, and organize unstructured text without sacrificing the durability of plain files?

The universal answer across modern local-first tools (including Obsidian, Logseq, Foam, Hugo, and Astro) is YAML frontmatter. Frontmatter embeds a strongly-typed metadata payload at the very top of a plain Markdown document. When parsed by indexing engines like Obsidian Dataview or SQLite FTS5, this metadata elevates a loose folder of text files into a high-performance relational database.

In this architectural guide, we unpack the principles of frontmatter schema design. We present battle-tested templates for technical meeting notes, architectural decision records (ADRs), and sprint reviews, and demonstrate how automated capture engines like Oyma populate these schemas effortlessly.

---

1. Anatomy of Standards-Compliant Frontmatter

YAML (YAML Ain’t Markup Language) frontmatter must begin on the very first character of the file (Line 1, Column 1) and be enclosed between matching sets of triple dashes (---).

---
title: "Distributed Cache Architecture Review"
date: 2026-10-09
type: meeting-note
status: completed
attendees:
  - "[[Julian Thorne]]"
  - "[[Marcus Vance]]"
  - "[[Dr. Elena Rostova]]"
tags:
  - architecture
  - redis
  - infrastructure
action_items_count: 4
has_recording: true
---

1.1 Critical Data Types in Note Metadata

To ensure that query engines can filter and sort notes without type-coercion bugs, adhere strictly to canonical YAML types:

• ISO-8601 Dates: Always represent dates as YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ. Never use colloquial strings like "October 9th", which break chronological sorting.
• Wikilink Arrays: In Obsidian, enclosing names within double brackets inside quotes (e.g. attendees: ["[[Jane Doe]]"]) establishes active graph backlinks while preserving valid YAML syntax.
• Enumerated Status Keys: Standardize lifecycle states (e.g. draft, in-review, approved, archived) to enable pipeline queries.

---

2. Production Templates for Engineering Workflows

Below are three battle-tested frontmatter schemas designed for high-throughput technical organizations.

2.1 The Comprehensive Engineering Meeting Note Template

This template is optimized for technical deliberation meetings, sprint planning sessions, and architecture syncs:

---
title: "{{title}}"
date: {{date}}
time: {{time}}
type: meeting-note
category: architecture-review
project: "[[Project Apollo]]"
attendees:
  - "[[Jane Doe]]"
  - "[[John Smith]]"
tags:
  - meeting
  - sprint-planning
  - architecture
status: completed
source: "Oyma"
summary_status: verified
---

# {{title}}

## Quick Context
- **Date:** {{date}} ({{time}})
- **Project:** [[Project Apollo]]
- **Facilitator:** [[Jane Doe]]

---

## Executive Summary
> [!abstract] Briefing
> Summary of key discussion points and high-level architectural consensus.

---

## Key Decisions Made
- [x] **ADR-014:** Adopt RocksDB for local embedded state storage.
- [x] **Timeline:** Target Phase 1 delivery for end of Q4.

---

## Action Items
- [ ] **[[Jane Doe]]**: Draft RocksDB storage engine adapter by Friday.
- [ ] **[[John Smith]]**: Benchmark write amplification on APFS drives.

---

## Verbatim Discussion & Transcript
*Full searchable transcript captured locally via Oyma.*

2.2 The Architecture Decision Record (ADR) Template

For engineering teams memorializing technical design choices:

---
title: "ADR-042: Migration to Local SQLite FTS5"
date: 2026-10-09
type: adr
status: accepted
deciders:
  - "[[Julian Thorne]]"
  - "[[Marcus Vance]]"
tags:
  - adr
  - database
  - search
supersedes: "[[ADR-012]]"
---

# ADR-042: Migration to Local SQLite FTS5

## Context & Problem Statement
Our local note indexing engine experiences degraded search latency when scanning 10,000 Markdown documents using raw substring grep. We require a sub-millisecond local search engine.

## Decision Drivers
- Sub-5ms query response time across 20M words.
- Zero network telemetry or remote cloud dependencies.
- Zero external daemon dependencies.

## Considered Options
1. SQLite FTS5 Virtual Tables
2. Meilisearch local daemon
3. Ripgrep CLI subprocess

## Decision Outcome
Chosen option: **SQLite FTS5 Virtual Tables**, because it provides embedded C-level execution, Porter stemming, and BM25 relevance ranking with zero background daemon overhead.

---

3. Querying Frontmatter with Obsidian Dataview

The true power of YAML frontmatter manifests when you construct dynamic database views using the Obsidian Dataview plugin.

3.1 Displaying All Open Action Items Across Meetings

Instead of manually hunting through dozens of meeting files, you can insert a dynamic Dataview query into your project dashboard:

```dataview
TABLE file.link AS "Meeting", date AS "Date", attendees AS "Participants"
FROM "Meetings"
WHERE type = "meeting-note" AND contains(tags, "architecture")
SORT date DESC
LIMIT 10
```

This query scans your Meetings/ directory in memory and renders a clean, interactive table that updates automatically whenever a new meeting note is added.

3.2 Aggregating Uncompleted Tasks by Assignee

To track deliverables assigned to a specific engineer across all meetings:

```dataview
TASK
FROM "Meetings"
WHERE !completed AND contains(text, "Jane Doe")
SORT file.name DESC
```

Every open checkbox mentioning Jane Doe across hundreds of historical meeting notes will be aggregated into a single interactive checklist.

---

4. Validating Frontmatter at Scale: Schema Testing with Zod

When managing large knowledge repositories across an engineering organization, manual formatting errors—such as forgetting the closing quotes on a string or omitting a required date field—can corrupt Dataview tables and search indexes.

To prevent metadata degradation, you can execute automated CI/CD validation scripts using Zod and Node.js or Python:

import { z } from 'zod';
import matter from 'gray-matter';
import fs from 'fs';
import path from 'path';

// Define the strict frontmatter schema
const MeetingNoteSchema = z.object({
  title: z.string().min(3).max(80),
  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be YYYY-MM-DD'),
  type: z.literal('meeting-note'),
  attendees: z.array(z.string()).min(1),
  tags: z.array(z.string()),
  status: z.enum(['draft', 'in-progress', 'completed', 'archived']),
});

// Validate all files in the Meetings directory
function validateVaultMeetings(dirPath: string) {
  const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.md'));
  let errorCount = 0;

  for (const file of files) {
    const rawContent = fs.readFileSync(path.join(dirPath, file), 'utf8');
    const { data: frontmatter } = matter(rawContent);
    
    const result = MeetingNoteSchema.safeParse(frontmatter);
    if (!result.success) {
      console.error(`❌ Validation failed in ${file}:`, result.error.format());
      errorCount++;
    }
  }

  if (errorCount === 0) {
    console.log(`✅ All ${files.length} meeting notes passed frontmatter validation.`);
  }
}

By adding a pre-commit git hook running this validator, your vault maintains immaculate relational integrity across decades of note-taking.

---

5. Automated Frontmatter Generation with Oyma

The primary bottleneck in maintaining rigorous frontmatter schemas is human discipline. After an exhausting two-hour product review, engineers rarely want to manually format YAML arrays, ISO timestamps, and backlink tags.

This is where automated on-device capture engines provide immense leverage:

1. Automated Metadata Extraction: Oyma automatically extracts meeting start times, duration, calendar event titles, and detected attendee names.
2. Standardized Formatting: Oyma populates perfectly structured YAML frontmatter directly at the head of every transcript.
3. Frictionless Vault Integration: Notes are saved directly into your local directory or Obsidian vault, making them instantly visible to your Dataview tables without manual copy-pasting.

For ready-to-use Markdown templates across 12 operational categories, explore our open-source meeting note templates catalog and learn how to construct SQLite FTS5 full-text search indexes over your vault.

---

6. Advanced Automation: Dynamic DataviewJS Rollups

For knowledge architects who require advanced reporting across multiple projects, standard Dataview SQL queries can be augmented with DataviewJS (vanilla JavaScript executing inside Obsidian).

// Dynamic meeting rollup by project tag
const meetings = dv.pages('"40-Meetings"')
  .where(p => p.type === "meeting-note")
  .sort(p => p.date, "desc");

dv.table(
  ["Date", "Title", "Participants", "Action Items Count"],
  meetings.map(m => [
    m.date,
    m.file.link,
    m.attendees ? m.attendees.join(", ") : "N/A",
    m.file.tasks.length
  ])
);

By executing this script within your primary project dashboard, you generate an interactive summary table that reflects real-time changes across hundreds of meeting notes without ever modifying raw Markdown files.

---

6. Advanced Automation: Dynamic DataviewJS Rollups

For knowledge architects who require advanced reporting across multiple projects, standard Dataview SQL queries can be augmented with DataviewJS (vanilla JavaScript executing inside Obsidian).

// Dynamic meeting rollup by project tag
const meetings = dv.pages('"40-Meetings"')
  .where(p => p.type === "meeting-note")
  .sort(p => p.date, "desc");

dv.table(
  ["Date", "Title", "Participants", "Action Items Count"],
  meetings.map(m => [
    m.date,
    m.file.link,
    m.attendees ? m.attendees.join(", ") : "N/A",
    m.file.tasks.length
  ])
);

By executing this script within your primary project dashboard, you generate an interactive summary table that reflects real-time changes across hundreds of meeting notes without ever modifying raw Markdown files.

6.2 Automated Frontmatter Linting with Custom Git Hooks

To guarantee schema uniformity across multi-contributor documentation vaults, teams can enforce frontmatter standards before committing Markdown files to Git. Using a lightweight Node.js CLI script, you can validate required keys (title, date, type, tags) across your repositories:

#!/usr/bin/env bash
# Validate frontmatter keys on modified Markdown files
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.md$'); do
  node -e "
    const fs = require('fs');
    const content = fs.readFileSync('$file', 'utf8');
    const match = content.match(/^---
([\s\S]*?)
---/);
    if (!match) {
      console.error('ERROR: Missing YAML frontmatter in $file');
      process.exit(1);
    }
    const yaml = match[1];
    const required = ['title', 'date', 'type'];
    for (const req of required) {
      if (!new RegExp('^' + req + ':', 'm').test(yaml)) {
        console.error('ERROR: Missing required key "' + req + '" in $file');
        process.exit(1);
      }
    }
  "
  if [ $? -ne 0 ]; then
    echo "Frontmatter validation failed for $file. Aborting commit."
    exit 1
  fi
done

This automated verification ensures that every meeting note conforms strictly to your vault’s relational schema before entering version control.

6.3 Bidirectional Metadata Linking: Inline Dataview Attributes

Beyond top-level YAML blocks, Obsidian supports inline metadata fields formatted as [key:: value]. Inline fields allow you to assign attributes to specific sentences or action items directly within narrative prose:

• * [ ] Review pull request 410 [assignee:: [[Marcus Vance]]] [due:: 2026-10-15]
• * [x] Benchmark ANE throughput [status:: complete] [verified_by:: [[Dr. Elena Rostova]]]

By structuring action items with inline metadata, Dataview queries can dynamically filter tasks by assignee and completion status across the entire vault without parsing full-text prose.