Commune

Frontmatter Convention

4 min read

Every article in the library carries YAML frontmatter that follows a fixed schema. The schema is designed so the library can be queried as structured data — not just read as prose — via Obsidian’s Dataview plugin or any tool that ingests YAML.

The same schema works whether you’re browsing in Obsidian, querying via the Obsidian MCP, or rendering with Quartz.

The Schema

---
title: "Article Title"
aliases: []
description: "One-sentence summary of what this article covers."
category: philosophy
subcategory: ""
type: essay
status: published
tags: [topic1, topic2]
created: 2026-02-01
updated: 2026-04-25
sources: []
related: []
people: []
works: []
timeframe: ""
---

Field Reference

Required

FieldTypeNotes
titlestringDisplay title. Quote if it contains a colon.
descriptionstringSingle sentence; appears in search and link previews.
categorystringTop-level folder name: art, creative, games, health, infrastructure, meta, philosophy, projects, technology.
typeenumessay, biography, reference, pattern, guide, stub, meta. See Type values.
statusenumstub, draft, published, needs-review.
tagsarray of stringsFlat controlled vocabulary; no nesting, no spaces (use hyphens).
createdISO dateYYYY-MM-DD. Date the article was first added.
updatedISO dateYYYY-MM-DD. Most recent substantive edit.

Optional

FieldTypeNotes
aliasesarray of stringsAlternate names used to find the article. Obsidian uses these for autocomplete.
subcategorystringSubfolder name when nested (movements, artists, places, dnd, agent-systems). Empty string if top-level only.
sourcesarray of stringsCitations in "Author, Title (Year)" form. Inline footnotes are still fine; this field is for queryable bibliographies.
relatedarray of stringsWikilink targets, e.g. ["[[anarchism]]", "[[mutual-aid]]"]. Mirrors the See Also section so it’s machine-queryable.
peoplearray of stringsNamed individuals whose work or biography this article discusses. Use canonical name: "Guy Debord", not "Debord".
worksarray of stringsNamed books, films, projects, or art works the article centers on.
timeframestringA date range or single year, e.g. "1919-1933", "1971-1973", "c. 1500". For movements, biographies, historical events.

Type values

  • essay — argumentative or analytical prose around a concept (most philosophy/creative articles).
  • biography — focused on a person’s life and work.
  • reference — structured factual material (specifications, schemas, tables of values).
  • pattern — a recurring solution to a problem, with conditions of use (most technology/infrastructure articles).
  • guide — instructional walkthrough.
  • stub — placeholder with minimal content awaiting expansion.
  • meta — about the library itself (this article, contributing guidance).

Status values

  • stub — under ~50 lines or marked explicitly as a placeholder; meaningful gaps remain.
  • draft — substantive content but unfinished; expect rough edges.
  • published — content is complete enough to rely on.
  • needs-review — flagged for fact-checking, restructuring, or editorial pass.

Why this schema

Obsidian’s Dataview plugin lets us query the library like a database. With consistent frontmatter, we can ask:

TABLE category, type, updated
FROM ""
WHERE status = "stub"
SORT updated ASC

Or more usefully:

LIST
FROM ""
WHERE contains(people, "Guy Debord")

Without a fixed schema, none of this works — the field names drift, dates get formatted four different ways, and arrays sometimes hold strings and sometimes nested objects. Every article that follows the convention strengthens the whole library; every one that doesn’t is a hole in every query.

Notes on Obsidian / Dataview behavior

  • Dates must be unquoted ISO strings (2026-04-25, not "2026-04-25") for Dataview to parse them as date values.
  • Arrays should be flow-style ([a, b, c]) or block-style (- a lines) — both work, but be consistent within a file.
  • Strings containing : must be quoted to avoid YAML parsing errors.
  • Wikilinks inside YAML arrays (related: [[[some-article]]]) need the double-bracket form quoted as a string: related: ["[[some-article]]"]. Dataview understands either form, but the quoted form is safer for YAML parsers.
  • Empty optional fields can be omitted entirely or written as field: "" / field: []. Empty placeholders are clearer for humans skimming; absence is cleaner for machines.

Tag conventions

Tags are a flat controlled vocabulary. Pick from existing tags before introducing new ones; check MEMORY.md-style audits or a quick grep "^tags:" content/**/*.md to see what’s in use.

Common tag families:

  • Subject area: philosophy, art, cybernetics, anarchism, health, games
  • Form: biography, pattern, index, stub
  • Domain: dnd, dataviz, infrastructure, governance

Avoid:

  • Single-use tags (a tag that appears in one article doesn’t cluster anything).
  • Tags that duplicate the category or subcategory exactly (redundant).
  • Multi-word phrases (mutual aid → mutual-aid).

What goes in description vs the lead paragraph

description is one sentence, written for someone who has not opened the article. The lead paragraph can assume the reader has decided to read.

Bad: description: "An article about Guy Debord." Good: description: "Founder of the Situationist International; theorized the spectacle and pioneered détournement."

See Also

Graph View

Backlinks