Module

orchestration.content

Content discovery and setup orchestration for Bengal SSG.

Handles content and asset discovery, page/section reference setup, and cascading frontmatter.

View source
1 Class

Classes

ContentOrchestrator
Handles content and asset discovery. Responsibilities: - Discover content (pages and sections)…
12

Handles content and asset discovery.

Responsibilities:

  • Discover content (pages and sections)
  • Discover assets (site and theme)
  • Set up page/section references for navigation
  • Apply cascading frontmatter from sections to pages

Methods 3

discover
Discover all content and assets. Main entry point called during build.
4 None 
def discover(self, incremental: bool = False, cache: Any | None = None, build_context: BuildContext | None = None, build_cache: Any | None = None) -> None

Discover all content and assets.

Main entry point called during build.

Parameters 4
incremental bool

Whether this is an incremental build (enables lazy loading)
cache Any | None

PageDiscoveryCache instance (required if incremental=True)
build_context BuildContext | None

Optional BuildContext for caching content during discovery. When provided, raw file content is cached for later use by validators, eliminating redundant disk I/O during health checks.
build_cache Any | None

Optional BuildCache for registering autodoc dependencies. When provided, enables selective autodoc rebuilds.
discover_content
Discover all content (pages, sections) in the content directory. Supports opti…
5 None 
def discover_content(self, content_dir: Path | None = None, incremental: bool = False, cache: Any | None = None, build_context: BuildContext | None = None, build_cache: Any | None = None) -> None

Discover all content (pages, sections) in the content directory.

Supports optional lazy loading with PageProxy for incremental builds. When build_context is provided, raw file content is cached for later use by validators (build-integrated validation).

Parameters 5
content_dir Path | None

Content directory path (defaults to root_path/content)
incremental bool

Whether this is an incremental build (enables lazy loading)
cache Any | None

PageDiscoveryCache instance (required if incremental=True)
build_context BuildContext | None

Optional BuildContext for caching content during discovery. When provided, raw file content is cached for later use by validators, eliminating redundant disk I/O during health checks.
build_cache Any | None

Optional BuildCache for registering autodoc dependencies. When provided, enables selective autodoc rebuilds.
discover_assets
Discover all assets in the assets directory and theme assets.
1 None 
def discover_assets(self, assets_dir: Path | None = None) -> None

Discover all assets in the assets directory and theme assets.

Parameters 1
assets_dir Path | None

Assets directory path (defaults to root_path/assets)
Internal Methods 9
__init__
Initialize content orchestrator.
1 None 
def __init__(self, site: Site)

Initialize content orchestrator.

Parameters 1
site Site

Site instance to populate with content
_discover_autodoc_content
Generate virtual autodoc pages if enabled.
1 tuple[list[Any], li… 
def _discover_autodoc_content(self, cache: Any | None = None) -> tuple[list[Any], list[Any]]

Generate virtual autodoc pages if enabled.

Parameters 1
cache Any | None

Optional BuildCache for registering autodoc dependencies. Enables selective rebuilding of autodoc pages in incremental builds.
Returns

tuple[list[Any], list[Any]] —

Tuple of (pages, sections) from virtual autodoc generation. Returns ([], []) if virtual autodoc is disabled.

_log_autodoc_summary
Log a summary of autodoc run results.
1 None 
def _log_autodoc_summary(self, result: Any) -> None

Log a summary of autodoc run results.

Parameters 1
result Any

AutodocRunResult with counts and failure details
_setup_page_references
Set up page references for navigation (next, prev, parent, etc.). Delegates to…
0 None 
def _setup_page_references(self) -> None

Set up page references for navigation (next, prev, parent, etc.).

Delegates to Site._setup_page_references() for the canonical implementation. This ensures a single source of truth for page-section reference setup.

_apply_cascades
Apply cascading metadata from sections to their child pages and subsections. S…
0 None 
def _apply_cascades(self) -> None

Apply cascading metadata from sections to their child pages and subsections.

Section _index.md files can define metadata that automatically applies to all descendant pages. This allows setting common metadata at the section level rather than repeating it on every page.

Cascade metadata is defined in a section's _index.md frontmatter:

_set_output_paths
Set output paths for all discovered pages. This must be called after discovery…
0 None 
def _set_output_paths(self) -> None

Set output paths for all discovered pages.

This must be called after discovery and cascade application but before any code tries to access page.url (which depends on output_path).

Setting output_path early ensures:

  • page.url returns correct paths based on file structure
  • Templates can access page.url without getting fallback slug-based URLs
  • xref_index links work correctly
  • Navigation links have proper URLs
_check_weight_metadata
Check for documentation pages without weight metadata. Weight is important for…
0 None 
def _check_weight_metadata(self) -> None

Check for documentation pages without weight metadata.

Weight is important for sequential content like docs and tutorials to ensure correct navigation order. This logs info (not a warning) to educate users about weight metadata.

_build_xref_index
Build cross-reference index for O(1) page lookups. Creates multiple indices to…
0 None 
def _build_xref_index(self) -> None

Build cross-reference index for O(1) page lookups.

Creates multiple indices to support different reference styles:

  • by_path: Reference by file path (e.g., 'docs/installation')
  • by_slug: Reference by slug (e.g., 'installation')
  • by_id: Reference by custom ID from frontmatter (e.g., 'install-guide')
  • by_heading: Reference by heading text for anchor links
  • by_anchor: Reference by explicit anchor ID (e.g., {#install})

Performance: O(n) build time, O(1) lookup time Thread-safe: Read-only after building, safe for parallel rendering

_get_theme_assets_dir
Get the assets directory for the current theme.
0 Path | None 
def _get_theme_assets_dir(self) -> Path | None

Get the assets directory for the current theme.

Returns

Path | None —

Path to theme assets or None if not found