validate-md
Validates markdown files with YAML frontmatter against JSON Schema definitions.
When & Why to Use This Skill
The validate-md skill is a specialized utility designed to ensure data integrity and consistency within Markdown-based workflows. By validating YAML frontmatter against predefined JSON Schema definitions, it automates the quality assurance process for structured content. This tool is essential for developers and content managers who need to prevent metadata errors, enforce documentation standards, and maintain high-quality data in static site generators or content-driven applications.
Use Cases
- Static Site Metadata Validation: Automatically verify that blog posts, documentation, or landing pages in frameworks like Hugo, Jekyll, or Next.js contain all required YAML fields such as 'title', 'date', and 'author' before deployment.
- CI/CD Pipeline Integration: Incorporate the validation script into automated workflows (e.g., GitHub Actions) to block builds or pull requests if Markdown files fail to meet the structural requirements defined in the schema.
- Documentation Consistency: Ensure technical documentation follows a strict style guide by validating that specific metadata properties are present and correctly formatted across large repositories.
- Data-Driven Markdown Management: Maintain the reliability of Markdown-based CRM systems or project trackers by identifying missing or invalid data points in frontmatter fields like 'status', 'priority', or 'assigned_to'.
| name | validate-md |
|---|---|
| description | Validates markdown files with YAML frontmatter against JSON Schema definitions. |
| allowed-tools | [Bash, Read, Glob] |
Validating Markdown Files
Instructions
Run validation script for the target directory containing a
schema.yamlfile:python validate-md.py <directory>Review results:
- Success:
✓ OK: filename.md is valid - Errors: Shows validation error, field path, and file location
- Success:
Examples
Example 1: Validate contacts directory
python validate-md.py crm/contacts
Output:
✓ OK: smith-john.md is valid
✓ OK: doe-jane.md is valid
✓ SUCCESS: All 2 files are valid!
Example 2: Validation error - missing required field
python validate-md.py crm/opportunities
Output:
❌ deal-2024-q1.md validation error: 'stage' is a required property
In file: crm/opportunities/deal-2024-q1.md
Fix: Add stage: qualified to the frontmatter.
Scripts
validate-md.pythe python validation script
Required Python Packages
- pyyaml - for parsing YAML frontmatter
- jsonschema - for validating against JSON Schema