MarkdownMatters: A Specification for Comprehensive Document Metadata

Introduction

MarkdownMatters defines an extended set of conventions for managing diverse metadata within a single Markdown document. It formalizes three distinct "Matter" zones—Frontmatter, Contentmatter, and Tailmatter—to cleanly separate configuration data by its primary stakeholder and lifecycle stage (Publisher, Author, and Editor/QA).

The goal is to create Markdown files that are robustly self-describing, supporting advanced automation, quality assurance (QA), and AI agent integration without compromising the file's core compatibility or readability.

The Three Matter Zones

The MarkdownMatters specification organizes metadata based on its location and purpose, ensuring separation of concerns and graceful degradation in standard Markdown environments.

1. Frontmatter (Publisher/Tooling Configuration)

This is the standard, well-known metadata block used for file-level configuration.

Feature	Specification	Purpose
Location	Must be the very first content in the file.	Tool-first access for immediate configuration (e.g., templating).
Format	YAML, TOML, or JSON (YAML is highly recommended).	Structured data with native support for namespacing.
Delimiter	`---` (or equivalent for TOML/JSON).	Standard convention; tooling must strip this before publishing.
Access Principle	Tool-Controlled. Systems should use nested keys to isolate their configuration (e.g., `hugo:`, `cms_config:`).

2. Contentmatter (Author/Contextual Data)

This refers to contextual metadata intended for inclusion within the content flow, often near the text it describes. This primarily leverages the MultiMarkdown (MMD) key-value convention.

Feature	Specification	Purpose
Location	Anywhere within the main content body.	Data is relevant to the section it appears in.
Format	Simple `Key: Value` lines (MMD convention).	Simple, plain-text format for user flexibility.
Delimiter	None (standard line structure).	Easy for authors to insert; tooling must scan the entire body.
Access Principle	Author-Flexible. Used for inline definitions, abstracts, or citations that should remain highly visible to the author.

3. Tailmatter (Editor/QA Requirements)

This is the custom extension for post-content quality assurance, review checklists, and automated agent configurations.

Feature	Specification	Purpose
Location	Must be the very last block of content.	Data relates to post-creation processes (validation, review).
Format	Fenced Code Block containing YAML or JSON.	Structured data that is easily ignored by standard renderers.
Delimiter	```yaml [reserved-tag]	The reserved tag isolates the data for the specific CLI/tool.
Access Principle	Editor-Driven. Used for editorial sign-off, QA checklists, and agent prompts.

Tailmatter Specification Details

The Tailmatter is identified by a YAML Fenced Code Block placed at the end of the document, typically separated from the main content by a horizontal rule (---).

1. The Reserved Tag

The specification requires the use of the tag yaml tailmatter (or json tailmatter) in the info string of the fenced code block:

---
# Main content ends here.

```yaml tailmatter
# Key-value data goes here.


### 2. Core Namespaces for Tailmatter

The following namespaces are reserved within the Tailmatter block to support the defined use cases:

| Key | Type | Purpose | CLI Function |
| :--- | :--- | :--- | :--- |
| **`qa_checklist`** | List of objects | Defines mandatory quality standards and current completion status. | `tailmatter check` |
| **`editorial`** | Object | Stores sign-off data, reviewer names, and final publication status. | `tailmatter set` / `tailmatter get` |
| **`agent_config`** | Object | Specifies the persona, prompt, and scope for an AI agent run. | `tailmatter agent` |

### 3. Example Tailmatter Block

```yaml tailmatter
qa_checklist:
  - requirement: "All section headers are level 2 or lower."
    complete: true
  - requirement: "External links verified."
    complete: false

editorial:
  status: "In Review"
  last_reviewed_by: "jsmith"
  version: 1.1

agent_config:
  role: "documentation_proofreader"
  prompt_prefix: "Analyze the content for tone consistency. Report any passive voice."
  access_scope: "content"

Tooling and Implementation

The separation of these three zones allows for focused CLI tooling. A dedicated tailmatter CLI utility is designed to interact only with the Tailmatter block, leaving the Frontmatter and Contentmatter to be handled by other dedicated tools (like SSGs and MMD processors).

This design ensures that MarkdownMatters files remain maximally compatible with the broader Markdown ecosystem while unlocking sophisticated metadata management capabilities.