Module

debug.explainer

Page explainer - generates explanations for how pages are built.

Provides complete traceability for any page: source file, template chain, dependencies, shortcodes, cache status, output location, and diagnostics.

Key Concepts:

  • Read-only introspection: No side effects, pure analysis
  • Template chain resolution: Shows full inheritance
  • Dependency tracking: Content, templates, data, assets
  • Cache status: HIT/MISS/STALE with reasons

Related Modules:

  • bengal.debug.models: Data models for explanation components
  • bengal.debug.reporter: Rich terminal output formatting
  • bengal.rendering.template_engine: Template resolution
  • bengal.cache.build_cache: Cache status introspection

See Also:

  • plan/active/rfc-explain-page.md: Design RFC
View source
1 Class

Classes

PageExplainer
Generate explanations for how pages are built. Provides complete traceability for any page includi…
16

Generate explanations for how pages are built.

Provides complete traceability for any page including source info, template chain, dependencies, cache status, and diagnostics.

Creation:

Direct instantiation: PageExplainer(site, cache=None, template_engine=None)
  • Created by CLI explain command
  • Requires Site instance with discovered content

Attributes

Name Type Description
site —

Site instance with pages and configuration
cache —

Optional BuildCache for cache status
template_engine —

Optional TemplateEngine for template resolution Thread Safety: Thread-safe. Read-only operations only.

Methods 1

explain
Generate complete explanation for a page.
3 PageExplanation 
def explain(self, page_path: str, verbose: bool = False, diagnose: bool = False) -> PageExplanation

Generate complete explanation for a page.

Parameters 3
page_path str

Path to the page (relative to content dir or source_path)
verbose bool

Include additional details (timing, template variables)
diagnose bool

Check for issues (broken links, missing assets)
Returns

PageExplanation —

PageExplanation with all available information

Internal Methods 15
__init__
Initialize the page explainer.
3 None 
def __init__(self, site: Site, cache: BuildCache | None = None, template_engine: TemplateEngine | None = None) -> None

Initialize the page explainer.

Parameters 3
site Site

Site instance with pages and configuration
cache BuildCache | None

Optional BuildCache for cache status introspection
template_engine TemplateEngine | None

Optional TemplateEngine for template resolution
_find_page
Find a page by path. Searches by: 1. Exact source_path match 2. Relative path …
1 Page | None 
def _find_page(self, page_path: str) -> Page | None

Find a page by path.

Searches by:

  1. Exact source_path match
  2. Relative path match (without content/ prefix)
  3. Partial path match (filename or partial path)
Parameters 1
page_path str

Path to search for
Returns

Page | None —

Page if found, None otherwise

_get_source_info
Get source file information.
1 SourceInfo 
def _get_source_info(self, page: Page) -> SourceInfo

Get source file information.

Parameters 1
page Page
Returns

SourceInfo

_resolve_template_chain
Resolve the complete template inheritance chain.
1 list[TemplateInfo] 
def _resolve_template_chain(self, page: Page) -> list[TemplateInfo]

Resolve the complete template inheritance chain.

Parameters 1
page Page

Page to resolve templates for
Returns

list[TemplateInfo] —

List of TemplateInfo in inheritance order (child first)

_get_template_name
Get the template name for a page.
1 str | None 
def _get_template_name(self, page: Page) -> str | None

Get the template name for a page.

Parameters 1
page Page
Returns

str | None

_resolve_chain_from_engine
Resolve template chain using the template engine.
1 list[TemplateInfo] 
def _resolve_chain_from_engine(self, template_name: str) -> list[TemplateInfo]

Resolve template chain using the template engine.

Parameters 1
template_name str
Returns

list[TemplateInfo]

_get_theme_from_path
Extract theme name from template path.
1 str | None 
def _get_theme_from_path(self, template_path: Path | None) -> str | None

Extract theme name from template path.

Parameters 1
template_path Path | None
Returns

str | None

_extract_extends
Extract extends directive from Jinja2 template.
1 str | None 
def _extract_extends(self, content: str) -> str | None

Extract extends directive from Jinja2 template.

Parameters 1
content str
Returns

str | None

_extract_includes
Extract include directives from Jinja2 template.
1 list[str] 
def _extract_includes(self, content: str) -> list[str]

Extract include directives from Jinja2 template.

Parameters 1
content str
Returns

list[str]

_get_dependencies
Get all dependencies for a page.
1 DependencyInfo 
def _get_dependencies(self, page: Page) -> DependencyInfo

Get all dependencies for a page.

Parameters 1
page Page
Returns

DependencyInfo

_extract_asset_refs
Extract asset references from content.
1 list[str] 
def _extract_asset_refs(self, content: str) -> list[str]

Extract asset references from content.

Parameters 1
content str
Returns

list[str]

_get_shortcode_usage
Extract shortcode/directive usage from page content.
1 list[ShortcodeUsage] 
def _get_shortcode_usage(self, page: Page) -> list[ShortcodeUsage]

Extract shortcode/directive usage from page content.

Parameters 1
page Page
Returns

list[ShortcodeUsage]

_get_cache_status
Get cache status for a page.
1 CacheInfo 
def _get_cache_status(self, page: Page) -> CacheInfo

Get cache status for a page.

Parameters 1
page Page
Returns

CacheInfo

_get_output_info
Get output information for a page.
1 OutputInfo 
def _get_output_info(self, page: Page) -> OutputInfo

Get output information for a page.

Parameters 1
page Page
Returns

OutputInfo

_diagnose_issues
Diagnose potential issues with a page.
1 list[Issue] 
def _diagnose_issues(self, page: Page) -> list[Issue]

Diagnose potential issues with a page.

Parameters 1
page Page
Returns

list[Issue]