Frontmatter Design and Automatic learning_time Normalization: Managing Quality for AI-Generated Articles at Scale
Introduction
Frontmatter is the configuration information written at the top of an article file. It defines the article’s title, publication date, tags, estimated reading time, and other settings. When AI generates an article, it writes this configuration information at the same time — but the values it sets can end up not matching the actual length of the article. This article explains why I introduced automatic normalization of the learning_time field (the estimated reading time for an article) and how the mechanism works.
The Problem: learning_time Did Not Reflect the Actual Article
This site sets a learning_time field on documentation articles. It indicates roughly how many minutes the article takes to read, and serves as a guideline for readers to decide how much time to set aside.
When AI generates an article, it sets this value, but it was not always consistent with the actual word count. Specifically, cases arose where an article’s content had grown but learning_time: 3 minutes remained unchanged in the frontmatter, or where a short article had learning_time: 15 minutes set.
In this state, readers who started reading based on the displayed time would sometimes find the actual reading time significantly different.
The Solution: Automatic Normalization Based on Word Count
To address this, I introduced a script that calculates the word count of an article and automatically sets an appropriate learning_time value.
The mechanism works as follows.
- Read the article file
- Calculate the word count of the body (excluding the frontmatter section)
- Calculate reading time based on average Japanese reading speed (approximately 400 to 500 characters per minute)
- Write the calculated value into the
learning_timefield
I configured this process to run at the same time as existing scripts such as node scripts/ensure-slugs.js.
The Consistency Gained Through Automation
With manual learning_time setting, it is necessary to count characters, calculate, and enter the value each time an article is written. This is not a problem when there are few articles, but as the number grows, it becomes easy for updates to be missed. When an article is revised and the word count changes, it is also easy to forget to update learning_time.
By introducing the automatic normalization script, even when article content changes, learning_time is automatically updated to the correct value the next time the script runs. The situation where the displayed reading time diverges from the article length due to a setting error or missed update no longer occurs.
“Automation provides more consistency than having a person set values manually each time” is a principle that applies broadly to managing configuration information. Values that vary based on other factors — like reading time depending on word count — are well suited to automation.
The Scope of Automation in Frontmatter Design
Automating every frontmatter field is not necessarily the right approach. Fields such as title, description, and tags require an understanding of the article’s content to set correctly, and are fields that a person should review.
On the other hand, fields whose values are determined by calculation or conversion — such as word count, reading time, and slug (the URL path) — are well suited to automation. Using the criterion “Can this field’s value be mechanically calculated from another element of the article?” makes it easier to determine what to automate.
Summary
Frontmatter values that AI sets when generating an article can fall out of sync with the article’s actual content. Fields such as learning_time that can be calculated from word count can be managed with an automatic normalization script to maintain consistency. Holding the principle “automate values that vary based on other factors” when managing configuration information makes it easier to maintain quality as the number of articles grows.