Skip to main content

Frontmatter Validation

RallyPoynt OS includes several tools to help ensure that all content files have the appropriate frontmatter metadata according to our Frontmatter Standards. This guide explains how to use these validation tools as a contributor.

Validation Tools Overview

There are multiple ways to validate frontmatter in your content:

  1. Pre-commit Hook: Automatically validates frontmatter in staged files before each commit
  2. CLI Tool: Run the validation script manually to check specific files or directories
  3. GitHub Actions: Automated validation runs on pull requests or commits to main
  4. Development Server: Validation runs when starting the dev server (npm start)

Using the Pre-commit Hook

When you clone the repository and run npm install, the Git hooks are automatically installed. The pre-commit hook will validate the frontmatter of any Markdown files you're about to commit.

If validation fails, the commit will be blocked with an error message. You can:

  • Fix the issues and try committing again
  • Run npm run validate-frontmatter:fix to automatically fix common issues
  • Use git commit --no-verify to bypass the validation check (not recommended)

If you need to reinstall the hooks, run:

npm run install-hooks

Using the CLI Validation Tool

You can manually validate frontmatter using the command line interface:

# Validate all files in docs/
npm run validate-frontmatter

# Show validation summary only
npm run validate-frontmatter -- --summary

# Automatically fix common issues
npm run validate-frontmatter:fix

# Validate a specific directory
npm run validate-frontmatter -- --dir="docs/components"

# Show detailed output
npm run validate-frontmatter -- --verbose

GitHub Actions Workflow

Our repository includes a GitHub Actions workflow that automatically validates frontmatter on:

  • All pull requests targeting the main branch
  • All pushes to the main branch

The workflow will:

  1. Check out the code
  2. Install dependencies
  3. Run the frontmatter validation
  4. Generate a validation report
  5. Flag the pull request if validation fails

You can see the validation report in the "Checks" tab of your pull request. Fixing frontmatter issues before merging is required.

Development Server Validation

When you run npm start to start the development server, the frontmatter validator plugin will automatically check all content files and report any issues in the console. This provides immediate feedback during development.

Common Validation Errors

Here are some common frontmatter validation errors and how to fix them:

  • Missing required field: Add the missing field (e.g., title, description)
  • Invalid value: Correct the value to match the expected format or value set
  • Invalid contentLevel: Use one of the allowed content levels (see Frontmatter Standards)
  • Missing recommended field: Add the recommended field for better content organization and discovery

Automatic Fixes

The --fix option can automatically fix many common issues:

npm run validate-frontmatter:fix

This will attempt to:

  • Add required fields with sensible defaults
  • Correct invalid values where possible
  • Add recommended fields based on content type
  • Update dates to the current date if missing

Validation Rules

The validation rules are based on the standards defined in Frontmatter Standards. Refer to that document for a complete list of required and recommended fields for each content type.