coulomb/markitect-main
2
0
Fork 0
Code Issues 61 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

Add MarkdownMatters

Bernd Worsch
2025-09-30 18:38:14 +00:00
parent 0754bacfd5
commit 648d8247c4
1 changed files with 104 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
MarkdownMatters.md Normal file

@@ -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.