From 648d8247c45c7fc9f76384e8c4596802fa014756 Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Tue, 30 Sep 2025 18:38:14 +0000 Subject: [PATCH] Add MarkdownMatters --- MarkdownMatters.md | 104 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 MarkdownMatters.md diff --git a/MarkdownMatters.md b/MarkdownMatters.md new file mode 100644 index 0000000..0220ec7 --- /dev/null +++ b/MarkdownMatters.md @@ -0,0 +1,104 @@ +# 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: + +````markdown +--- +# 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. \ No newline at end of file