# Validate and Fix URL: /bengal/docs/0.5.0/content/validation/validate-and-fix/ Section: validation Tags: validation, health-checks, auto-fix, lint -------------------------------------------------------------------------------- Validate and Fix Content Bengal's health system validates content and can automatically fix many common issues. Quick Start # Run all validators bengal check # Preview auto-fixes bengal fix --dry-run # Apply safe fixes bengal fix Validation Commands Basic Validation # Validate entire site bengal check # Validate specific file bengal check --file content/docs/getting-started.md # Validate changed files only (git-aware) bengal check --changed # Verbose output - show all checks, not just errors bengal check --verbose Validate During Build # Fail build on validation errors (recommended for CI) bengal build --strict # Validate templates before building bengal build --validate Check Specific Areas # Link checking (internal + external) bengal health linkcheck # Internal links only (fast) bengal health linkcheck --internal-only # External links only bengal health linkcheck --external-only # Exclude specific URL patterns bengal health linkcheck --exclude "^/api/preview/" Available Validators Bengal includes validators organized by phase: Core Validators Validator Checks Common Issues Links Internal/external links Broken links, moved pages Directives MyST directive syntax Unclosed fences, invalid options Configuration Site configuration Invalid YAML, missing required fields Navigation Page nav (next/prev, breadcrumbs) Broken navigation links Navigation Menus Menu structure and links Missing menu items, broken links Content Quality Validators Validator Checks Common Issues Anchors Heading IDs, [[#anchor]] refs Duplicate IDs, broken anchor links Cross-References Internal page references Invalid page references Taxonomies Tags/categories Orphan terms, inconsistent naming Connectivity Page link graph Orphan pages, poor connectivity Build & Output Validators Validator Checks Common Issues Rendering HTML output quality Template errors, undefined variables, missing social tags, malformed JSON-LD Output Generated pages, assets Missing output, structure errors Asset URLs Asset references in HTML Broken asset paths, fingerprinting mismatches, case issues Performance Build metrics Slow builds, large pages URL Collisions Duplicate output paths Multiple pages writing to same URL Production Validators Validator Checks Common Issues Sitemap sitemap.xml validity SEO issues, missing pages RSS Feed RSS/Atom feed quality Schema compliance, missing fields Fonts Font downloads, CSS Missing fonts, subsetting issues Ownership Policy Reserved namespaces Content in system directories Validation Output $ bengal check 🔍 Running health checks... ✅ Config: 3 checks passed ✅ Navigation: 5 checks passed ⚠️ Links: 2 warnings → content/docs/old-page.md references moved page → content/api/client.md has broken anchor #deprecated ❌ Directives: 1 error → content/tutorials/setup.md:45 - Unclosed code fence Summary: 1 error, 2 warnings, 8 passed Auto-Fix Preview Fixes Always preview before applying: bengal fix --dry-run Output: 🔧 Auto-Fix (dry run) Found 3 fix(es): • 2 safe (can be applied automatically) • 1 requires confirmation Safe fixes: • Fix unclosed code fence at content/tutorials/setup.md:45 • Add missing closing tag at content/api/reference.md:112 Would apply 2 fixes. Run without --dry-run to apply. Apply Fixes # Apply safe fixes only (default) bengal fix # Apply all fixes including those needing confirmation bengal fix --all # Ask before each fix bengal fix --confirm # Fix specific validator only bengal fix --validator Directives Fix Categories Safety Description Auto-Apply Safe Reversible, no side effects ✅ Yes Confirm May have side effects Needs --all or --confirm Unsafe Requires manual review Never auto-applied Common Auto-Fixes Directives: Missing closing fences (::: or ```) Incorrect fence syntax Invalid directive options Links: Update paths for renamed files Fix relative link depth Correct asset references Frontmatter: Fix YAML syntax errors Add missing required fields Correct date formats CI/CD Integration GitHub Actions name: Validate Docs on: [push, pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 with: python-version: '3.14' - name: Install Bengal run: pip install bengal - name: Validate Content run: bengal check --verbose - name: Check Links run: bengal health linkcheck --internal-only - name: Build (strict mode) run: bengal build --strict Pre-Commit Hook # .pre-commit-config.yaml repos: - repo: local hooks: - id: bengal-validate name: Validate Bengal content entry: bengal check --changed language: system pass_filenames: false Failing on Errors # Strict mode - treats warnings as errors bengal build --strict # Validate and exit with error code bengal check && echo "Validation passed" || echo "Validation failed" Custom Validators Create project-specific validation rules: # validators/require_author.py from bengal.health.base import BaseValidator from bengal.health.report import CheckResult, Severity class RequireAuthorValidator(BaseValidator): """Ensure all blog posts have an author.""" name = "Author Required" description = "Validates that blog posts have author metadata" def validate(self, site, build_context=None): results = [] for page in site.pages: # Only check blog posts if not page.section or page.section.name != "blog": continue if not page.metadata.get("author"): results.append(CheckResult( severity=Severity.ERROR, message=f"Missing author in {page.source_path}", recommendation="Add 'author: Your Name' to frontmatter", file_path=page.source_path, line_number=1, )) return results Register Custom Validator # bengal.py (site configuration) from validators.require_author import RequireAuthorValidator validators = [ RequireAuthorValidator(), ] Severity Levels Severity Meaning Strict Mode ERROR Must fix Fails build WARNING Should fix Fails build INFO Consider fixing Passes DEBUG Developer info Hidden Configuration Disable Validators # config/_default/health.yaml health: validators: links: enabled: true external: false # Skip external link checks performance: enabled: false # Disable performance checks Link Check Settings health: linkcheck: external: true max_concurrency: 10 timeout: 30 retries: 2 exclude: - "https://example.com/private/*" exclude_domains: - "localhost" - "*.internal.company.com" Validation Profiles Different validation for different contexts: # Full validation (CI) bengal check --verbose # Quick validation (local dev) bengal check --changed # Pre-deploy validation bengal health linkcheck && bengal build --strict Available profiles: Profile Use Case Checks writer Content authors Fast, content-focused theme-dev Theme developers Template validation developer Full development All checks, strict # Writer profile (fast, less strict) - default bengal check --profile writer # Theme developer profile bengal check --profile theme-dev # Developer profile (strict, all checks) bengal check --profile developer Troubleshooting False Positives Suppress specific check codes via CLI: # Ignore specific check codes bengal check --ignore H101 --ignore H202 Or in page frontmatter: --- validate: skip: - links # Skip link validation for this page - anchors # Skip anchor validation --- Or via configuration: # config/_default/health.yaml health: ignore_patterns: - "content/drafts/**" - "content/archived/**" Slow External Link Checks # Check internal links only (fast) bengal health linkcheck --internal-only # Exclude specific URL patterns bengal health linkcheck --exclude "^/api/preview/" Tip Tip Advanced options like --max-concurrency, --timeout, and --exclude-domain are available but hidden from help output. Use them when needed for fine-tuning. Validation Cache Validation uses the build cache for incremental checks: # Clear build cache (includes validation state) bengal clean --cache # Force full re-validation by clearing cache first bengal clean --cache && bengal check # Use incremental validation (only changed files) bengal check --incremental Quick Reference # Validate bengal check # Run all validators bengal check --changed # Only changed files bengal check --incremental # Use cached validation state bengal check --verbose # Show all checks bengal check --suggestions # Show quality suggestions bengal check --file path.md # Validate specific file bengal check --profile writer # Use writer profile (fast) bengal check --ignore H101 # Ignore specific check codes bengal check --watch # Watch mode (experimental) bengal check --templates # Validate template syntax # Auto-fix bengal fix --dry-run # Preview fixes bengal fix # Apply safe fixes bengal fix --all # Apply all fixes bengal fix --confirm # Ask before each fix bengal fix --validator Directives # Fix specific validator # Link checking bengal health linkcheck # Check all links bengal health linkcheck --internal-only # Internal only (fast) bengal health linkcheck --external-only # External only bengal health linkcheck --format json # JSON output for CI # Build bengal build --strict # Fail on warnings bengal build --validate # Validate before building # Clean bengal clean --cache # Clear build cache Info Seealso Validation Overview — Content quality strategies CLI Cheatsheet — Quick command reference Troubleshooting — Common issues -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1246 - Reading Time: 6 minutes