# Validate and Fix URL: /docs/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 validate # Preview auto-fixes bengal fix --dry-run # Apply safe fixes bengal fix Validation Commands Basic Validation # Validate entire site bengal validate # Validate specific file bengal validate --file content/docs/getting-started.md # Validate changed files only (git-aware) bengal validate --changed # Verbose output - show all checks, not just errors bengal validate --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 Output Generated pages, assets Missing output, structure errors Asset Processing Asset optimization Missing files, processing failures Asset URLs Asset references Broken asset paths, fingerprinting issues Performance Build metrics Slow builds, large pages Cache Integrity Incremental build cache Stale cache, invalidation issues Production Validators Validator Checks Common Issues Sitemap sitemap.xml validity SEO issues, missing pages RSS Feed RSS/Atom feed quality Schema compliance, missing fields Accessibility HTML accessibility Missing alt text, ARIA issues Fonts Font downloads, CSS Missing fonts, subsetting issues Validation Output $ bengal validate 🔍 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 validate --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 validate --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 validate && 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 validate --verbose # Quick validation (local dev) bengal validate --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 validate --profile writer # Theme developer profile bengal validate --profile theme-dev # Developer profile (strict, all checks) bengal validate --profile developer Troubleshooting False Positives Suppress specific check codes via CLI: # Ignore specific check codes bengal validate --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 validate # Use incremental validation (only changed files) bengal validate --incremental Quick Reference # Validate bengal validate # Run all validators bengal validate --changed # Only changed files bengal validate --incremental # Use cached validation state bengal validate --verbose # Show all checks bengal validate --suggestions # Show quality suggestions bengal validate --file path.md # Validate specific file bengal validate --profile writer # Use writer profile (fast) bengal validate --ignore H101 # Ignore specific check codes bengal validate --watch # Watch mode (experimental) bengal validate --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: 1243 - Reading Time: 6 minutes