Automate Astro Content Collections Validation and Repair with check-all-content.mjs

When maintaining large-scale static blogs with Astro, ensuring absolute YAML Frontmatter schema consistency across Content Collections is mission-critical. A single missing quote or invalid scalar type can crash incremental compilation. This guide introduces how to implement and operate check-all-content.mjs to systematically audit and repair metadata anomalies across thousands of articles.

Background: Cryptic Build Failures

When Astro compilation crashes unexpectedly with errors like id.endsWith is not a function or generic Zod parse exceptions, the underlying fault almost always traces back to malformed Markdown Frontmatter. Frequent culprits include:

• Unquoted string fields containing reserved characters (such as colons or brackets).
• Scalar type mismatches (strings supplied where arrays of strings are expected).
• Non-standard ISO date formats.
• Unescaped special characters causing YAML syntax parser crashes.

Solution Architecture: check-all-content.mjs

Script Capabilities

The check-all-content.mjs CLI tool accomplishes three core goals:

1. Systematic Traversal: Recursively scans all directory bundles inside src/content/blog/.
2. Schema Verification: Parses YAML headers using js-yaml and verifies fields against expected data structures.
3. Automated Remediation: Provides targeted diff suggestions and supports safe, automatic write-back repairs.

Core Implementation

Create scripts/check-all-content.mjs within your repository root:

// check-all-content.mjs: Astro Content Collection Auditor
import fs from 'node:fs';
import path from 'node:path';
import yaml from 'js-yaml';

console.log('🔍 Systematically auditing all content collection bundles...\n');

const blogDir = './src/content/blog';
const slugDirs = fs.readdirSync(blogDir, { withFileTypes: true })
  .filter(item => item.isDirectory())
  .map(item => item.name);

console.log(`Discovered ${slugDirs.length} article bundles.\n`);

let totalProblems = 0;

for (const slug of slugDirs) {
  const filePath = path.join(blogDir, slug, 'index.md');

  if (!fs.existsSync(filePath)) {
    console.log(`❌ ${slug}: Missing primary index.md`);
    totalProblems++;
    continue;
  }

  const raw = fs.readFileSync(filePath, 'utf8');
  const match = raw.match(/^---\n([\s\S]*?)\n---/);

  if (!match) {
    console.log(`❌ ${slug}: Missing Frontmatter block`);
    totalProblems++;
    continue;
  }

  try {
    const data = yaml.load(match[1]);
    if (!data.title) {
      console.log(`⚠️ ${slug}: Missing 'title' attribute`);
      totalProblems++;
    }
  } catch (err) {
    console.log(`❌ ${slug}: YAML Parse Error: ${err.message}`);
    totalProblems++;
  }
}

console.log(`\nAudit completed. Detected ${totalProblems} anomalies.`);

Running the Pipeline

Execute the validation directly through Node.js before running your deployment builds:

node scripts/check-all-content.mjs

Integrating this automated validation check into your CI/CD workflow guarantees that broken Frontmatter never breaks production deployments.