Why I Didn't Fully Automate My Front Matter Tooling

Background

Several months ago, I scaffold a command-line tool called fmc (Front Matter Checker)[https://github.com/Trones21/fmc]. It was designed to check — and optionally fix — the front matter of Markdown files in my documentation repo. I even added flags for --fix, --analyze, --fullConform, --removeExtraProps, and more.

But I shelved it. Until recently.

When I started working on a minimal implementation for serial full-read checking (as part of snail-to-cheetah), I ran into an issue. I debugged it by generating test files — and it turned out to be a dumb string literal bug in the generator. Once that was resolved, the logical next step was to run it on my actual Docusaurus project.

And something interesting happened.

---

The Power of Manual Progress

While I’ve always believed in Documentation Driven Development, I noticed a clear distinction between the type of tooling that helps and the tooling that feels over-engineered.

Example: fmc (as implemented in snail-to-cheetah repo)

Running fmc now gives me a satisfying audit of what’s missing or malformed. It:

• Tells me which files are missing description, tags, last_update, etc.
• Lets me manually improve them
• Shows less output every time I run it, which feels like progress

It’s not about auto-fixing everything. It’s about showing me what’s wrong — and letting me decide what to do about it.

In Contrast: kebabify

I also have a Bash script called kebabify that renames all .md and .mdx files to kebab-case:

#!/bin/bash

# List of folders to scan
DOC_FOLDERS=("projects" "technical" "not-technical" "internal")

# Converts all .md and .mdx files to kebab-case in those folders

for folder in "${DOC_FOLDERS[@]}"; do
  echo "Scanning: $folder"
  find "$folder" -type f \( -name "*.md" -o -name "*.mdx" \) | while read filepath; do
    dir=$(dirname "$filepath")
    file=$(basename "$filepath")
    ext="${file##*.}"
    name="${file%.*}"

    kebab=$(echo "$name" | \
      tr '[:upper:]' '[:lower:]' | \
      sed -E 's/[^a-z0-9]+/-/g' | \
      sed -E 's/^-+|-+$//g')

    newname="${kebab}.${ext}"

    if [[ "$file" != "$newname" ]]; then
      echo "Renaming: $file → $newname"
      mv "$filepath" "$dir/$newname"
    fi
  done
done

There’s no value in manually updating file names. It’s mechanical. So the script just enforces the rule and moves on.

---

What I Learned

1. You Can Find Key Pain Points By Doing the Manual Process In Bulk

I originally thought I’d automate title generation, description population, front matter reordering, etc. But after actually working with the docs and going through the manual process, I was reminded that it's often best to first gain real experience with the workflow. This helps identify the true pain points — and sometimes reveals that the manual process itself provides value, like visibility, context, and editorial awareness that automation might obscure.

• I’m fine writing descriptions by hand
• I already have frt to insert front matter templates
• I can ctrl+shift+p to generate UUIDs for IDs
• Most “fix” options are unnecessary

More importantly — it’s not worth the time investment right now. The cost of building 100% conformity and logic-based automation outweighs the value I’d get at this stage. I’m more focused on getting things to a solid baseline. If full conformity becomes important later, I can always revisit it.

I'd like to use fernvenue/ai-tags-generator tags based on content and in order to do that I need my docs to have front matter with a tags key.

2. fmc Became an Audit Tool, Not a Fix Tool

That shift was key. I no longer see fmc as something that auto-conforms files. I see it as a progress meter. A linter. A content audit.

3. The description Field Matters

Even though I write descriptions manually (for now), I discovered how valuable they are:

• Improve search results
• Provide hover previews
• Aid quick scanning on index pages

4. Creative vs. Mechanical Tools

This experience made me realize:

Tool	Role	Automation Style
fmc	Audit / Linter	Semi-manual
frt	Template Insertion	Assisted manual
kebabify	Filename Conformance	Fully automated

---

Final Thought

Automation is best when it removes tedium, not control. I'm glad I scaffolded the full CLI for fmc, but I'm even more glad I didn’t force myself to implement the entire feature set before it was actually useful. Using fmc with a minimal feature set was the right call.

Sometimes, less structure up front is what lets structure emerge naturally — and not every problem is worth solving right now.