Module

health.validators.anchors

Anchor validator for validating explicit anchors and cross-references.

Part of the explicit anchor system (RFC: plan/active/rfc-explicit-anchor-targets.md).

Validates:

  1. Duplicate anchor IDs within pages
  2. Broken [[#anchor]] cross-references

Key Features:

  • Detect duplicate anchor IDs in rendered HTML
  • Validate [[#anchor]] references against xref_index
  • Support for both heading anchors and {target} directive anchors

Related Modules:

  • bengal.health.base: BaseValidator interface
  • bengal.health.report: CheckResult for reporting
  • bengal.rendering.plugins.directives.target: Target directive
  • bengal.rendering.parsers.mistune: Heading {#id} syntax

See Also:

  • bengal/health/validators/cross_ref.py: General cross-reference validation
  • bengal/rendering/plugins/cross_references.py: [[link]] resolution
View source
1 Class 1 Function

Classes

AnchorValidator
Validates explicit anchors and [[#anchor]] cross-references. Performs two main validations: 1. Dup…
6

Validates explicit anchors and [[#anchor]] cross-references.

Performs two main validations:

  1. Duplicate anchors: Scans rendered HTML for duplicate id="..." attributes
  2. Broken references: Validates [[#anchor]] syntax against known anchors

Creation:

health_check.register(AnchorValidator())

Configuration:

In bengal.yaml:
health_check:
  validators:
    anchors: true  # Enable/disable anchor validation
Inherits from BaseValidator

Attributes

Name Type Description
strict —

If True, treat warnings as errors (for CI builds)

Methods 1

validate
Validate anchors across all site pages.
2 list[CheckResult] 
def validate(self, site: Site, build_context: Any | None = None) -> list[CheckResult]

Validate anchors across all site pages.

Parameters 2
site Site

Site to validate
build_context Any | None

Optional BuildContext (not used by this validator)
Returns

list[CheckResult] —

List of CheckResults for anchor issues

Internal Methods 5
__init__
Initialize anchor validator.
1 None 
def __init__(self, strict: bool = False)

Initialize anchor validator.

Parameters 1
strict bool

If True, report duplicate anchors as errors instead of warnings
_build_valid_anchor_set
Build set of all valid anchor IDs from xref_index. Combines both explicit anch…
1 set[str] 
def _build_valid_anchor_set(self, site: Site) -> set[str]

Build set of all valid anchor IDs from xref_index.

Combines both explicit anchors (from {#id} and {target}) and heading anchors for comprehensive validation.

Parameters 1
site Site

Site with built xref_index
Returns

set[str] —

Set of lowercase anchor IDs

_validate_duplicate_anchors
Check for duplicate anchor IDs within a single page. Scans rendered HTML for a…
1 list[CheckResult] 
def _validate_duplicate_anchors(self, page: Any) -> list[CheckResult]

Check for duplicate anchor IDs within a single page.

Scans rendered HTML for all id="..." attributes and reports any duplicates. Duplicate anchors cause navigation issues and invalid HTML.

Parameters 1
page Any

Page to validate
Returns

list[CheckResult] —

List of CheckResults for duplicate anchors

_validate_anchor_references
Check that all [[#anchor]] references resolve to existing anchors. Validates c…
2 list[CheckResult] 
def _validate_anchor_references(self, page: Any, valid_anchors: set[str]) -> list[CheckResult]

Check that all [[#anchor]] references resolve to existing anchors.

Validates cross-reference syntax against the set of known anchors from the xref_index.

Parameters 2
page Any

Page to validate
valid_anchors set[str]

Set of valid anchor IDs (lowercase)
Returns

list[CheckResult] —

List of CheckResults for broken references

_find_similar_anchors
Find anchors similar to the broken reference (for suggestions). Uses simple su…
2 list[str] 
def _find_similar_anchors(self, anchor: str, valid_anchors: set[str]) -> list[str]

Find anchors similar to the broken reference (for suggestions).

Uses simple substring matching to suggest possible fixes.

Parameters 2
anchor str

The broken anchor reference
valid_anchors set[str]

Set of valid anchors
Returns

list[str] —

List of up to 3 similar anchor names

Functions

create_anchor_validator
Factory function to create an AnchorValidator.
1 AnchorValidator 
def create_anchor_validator(strict: bool = False) -> AnchorValidator

Factory function to create an AnchorValidator.

Parameters 1

Name Type Default Description
strict bool False

If True, report duplicate anchors as errors

Returns

AnchorValidator —

Configured AnchorValidator