YAML Frontmatter for Content Pipelines: 50+ Articles Without an INDEX.md

#content #yaml #automation #frontmatter

TL;DR: Stop maintaining INDEX.md by hand. Add YAML frontmatter to every paste-ready file, then a 30-line scanner generates the index automatically. I have 50+ articles, 14 newsletters, and 6 SKU files all auto-indexed via this pattern.

The problem with INDEX.md

You start writing article 1. You add it to INDEX.md. Article 2 — you add it. Article 3, 4, 5...

By article 30, INDEX.md is out of sync. You forgot to add 3 articles. You added one with the wrong status. The status: ready flag is wrong because you published it but didn't update INDEX.md.

This is the classic "human-maintained source of truth" anti-pattern. Don't do this.

The frontmatter pattern

Every paste-ready file gets a YAML block at the top:

---
id: devto-55-manifest-frontmatter-content
title: "dev.to #55 - YAML Frontmatter for Content Pipelines"
category: content
priority: P1
status: ready
eta_min: 5
actions: [preview, copy-clipboard, open-devto]
tags: [content, yaml, automation]
created: 2026-05-07
publish_target_date: 2026-05-12
---

# YAML Frontmatter for Content Pipelines

(article body)

The frontmatter has 9 fields:

id — unique kebab-case ID
title — display title
category — content / product / roadmap / kit
priority — P0 (today) / P1 (this week) / P2 (next month)
status — draft / ready / live / published / archived
eta_min — how long to publish/use it
actions — array of dashboard buttons to render
tags — for searchability
created / publish_target_date — calendar tracking

The 30-line scanner

import yaml
from pathlib import Path

def scan_assets(root: Path):
    assets = []
    for md_file in root.rglob("*.md"):
        content = md_file.read_text(encoding='utf-8-sig')
        if not content.startswith("---"):
            continue
        try:
            _, yaml_block, _ = content.split("---", 2)
        except ValueError:
            continue
        try:
            meta = yaml.safe_load(yaml_block)
        except yaml.YAMLError:
            continue
        if not isinstance(meta, dict) or "id" not in meta:
            continue
        meta['_path'] = str(md_file.relative_to(root))
        assets.append(meta)
    return sorted(assets, key=lambda a: a.get('publish_target_date', '0'))

# Usage
assets = scan_assets(Path("reports"))
for a in assets:
    print(f"[{a['category']:8}] {a['priority']} {a['id']:40} → {a['_path']}")

Output:

[content ] P0 devto-50-50-articles-checkpoint            → devto-article-50-paste-ready.md
[content ] P0 substack-23-day-60-milestone               → substack-issue-23-day-60-milestone-paste-ready.md
[content ] P1 devto-55-manifest-frontmatter-content      → devto-article-55-paste-ready.md
...

No manual updates. Adding a new file with frontmatter automatically appears in the index.

Dashboard rendering

The dashboard reads the frontmatter and renders it as a table:

from flask import render_template_string
@app.route('/assets')
def assets():
    rows = scan_assets(Path("reports"))
    return render_template_string(TABLE_HTML, rows=rows)

TABLE_HTML = """
<table>
{% for r in rows %}
  <tr class="{{r.priority}}">
    <td>{{r.category}}</td>
    <td>{{r.id}}</td>
    <td>{{r.status}}</td>
    <td>{{r.publish_target_date}}</td>
    <td>
      {% if 'preview' in r.actions %}<a href="/preview/{{r._path}}">preview</a>{% endif %}
      {% if 'copy-clipboard' in r.actions %}<button onclick="copy('{{r._path}}')">copy</button>{% endif %}
      {% if 'open-devto' in r.actions %}<a href="https://dev.to/new" target="_blank">dev.to</a>{% endif %}
    </td>
  </tr>
{% endfor %}
</table>
"""

Three columns: ID, status, publish target date. Three buttons: preview, copy clipboard, open editor. Auto-generated from frontmatter.

Status transitions

The status field has 5 values that transition:

draft → ready → live (Substack/Gumroad) | published (dev.to) → archived

Update via shell one-liner:

sed -i 's/^status: ready$/status: published/' reports/devto-article-50-paste-ready.md

Or your dashboard exposes a button per row that does it.

What this saves

Manual INDEX.md update flow:

Write article → save file → open INDEX.md → add row → fix sort → save → commit

Frontmatter flow:

Write article (with frontmatter at top) → save file → done

Per-article time saved: 60 seconds.
For 50 articles: 50 minutes saved + zero index drift.

Bonus: stale-file detection

Once frontmatter is in place, you can write a stale-check:

from datetime import datetime, timedelta

stale = []
for a in scan_assets(Path("reports")):
    target = datetime.strptime(a.get('publish_target_date', '2099-01-01'), '%Y-%m-%d')
    if a['status'] in ['draft', 'ready'] and target < datetime.now() - timedelta(days=7):
        stale.append(a)

if stale:
    print(f"⚠ {len(stale)} stale assets:")
    for s in stale:
        print(f"  {s['id']} (target {s['publish_target_date']})")