Validation

Content validation and health checks

2 min read 393 words

Ensure content quality with health checks and automatic fixes.

Do I Need This?

Note

Skip this if: You manually check all links and content.
Read this if: You want automated quality assurance and CI/CD integration.

Validation Flow

flowchart LR A[Content] --> B[Validators] B --> C{Issues?} C -->|Yes| D[Report] C -->|No| E[Pass] D --> F{Auto-fixable?} F -->|Yes| G[Auto-fix] F -->|No| H[Manual fix needed]

Quick Start

# Run all checks
bengal validate

# Validate specific files
bengal validate --file content/page.md

# Only validate changed files (incremental)
bengal validate --changed

# Verbose output (show all checks)
bengal validate --verbose

# Show quality suggestions
bengal validate --suggestions

# Watch mode (validate on file changes)
bengal validate --watch

# Preview fixes
bengal fix --dry-run

# Apply safe fixes
bengal fix

# Apply all fixes including confirmations
bengal fix --all

# Fix specific validator only
bengal fix --validator Directives

Fixes common issues:

  • Unclosed directive fences
  • Invalid directive options
  • YAML syntax errors
# Fail build on issues
bengal build --strict

# Validate and exit with error code
bengal validate

The --strictflag makes warnings into errors.

Built-in Checks

Check What it validates
links Internal and external links work
assets Asset references exist
config Configuration is valid
navigation Menu structure is correct
rendering Templates render without errors
cross_ref Cross-references are valid
taxonomy Tags and categories are consistent
directives MyST directive syntax is correct
anchors Heading IDs are unique and valid

Custom Validators

Create project-specific rules by extendingBaseValidator:

# validators/custom.py
from bengal.health.base import BaseValidator
from bengal.health.report import CheckResult

class RequireAuthorValidator(BaseValidator):
    """Validator that checks for author field in frontmatter."""

    name = "Author Required"
    description = "Ensures all pages have an author field"

    def validate(self, site, build_context=None):
        results = []
        for page in site.pages:
            if not page.metadata.get("author"):
                results.append(CheckResult.error(
                    f"Missing author in {page.source_path}",
                    recommendation="Add 'author: Your Name' to frontmatter",
                    details=[str(page.source_path)],
                ))
        return results

Tip

CI integration: Addbengal validate to your CI pipeline to catch issues before deployment. Use --verbose to see all checks, or --suggestionsfor quality recommendations.