Module

core.site.discovery

Content discovery mixin for Site.

Provides methods for discovering content (pages, sections) and assets, and setting up page/section references.

Related Modules:

  • bengal.core.site.core: Main Site dataclass using this mixin
  • bengal.discovery.content_discovery: Content discovery implementation
  • bengal.discovery.asset_discovery: Asset discovery implementation
View source
1 Class

Classes

ContentDiscoveryMixin
Mixin providing content and asset discovery methods. Requires these attributes on the host class: …
8

Mixin providing content and asset discovery methods.

Requires these attributes on the host class:

  • root_path: Path
  • config: dict[str, Any]
  • pages: list[Page]
  • sections: list[Section]
  • assets: list[Asset]
  • theme: str | None
  • register_sections: Callable (from SectionRegistryMixin)
  • _get_theme_assets_chain: Callable (from ThemeIntegrationMixin)

Attributes

Name Type Description
root_path Path
config dict[str, Any]
pages list[Page]
sections list[Section]
assets list[Asset]
theme str | None

Methods 2

discover_content
Discover all content (pages, sections) in the content directory. Scans the con…
1 None 
def discover_content(self, content_dir: Path | None = None) -> None

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

Scans the content directory recursively, creating Page and Section objects for all markdown files and organizing them into a hierarchy.

Parameters 1
content_dir Path | None

Content directory path (defaults to root_path/content)
discover_assets
Discover all assets in the assets directory and theme assets. Scans both theme…
1 None 
def discover_assets(self, assets_dir: Path | None = None) -> None

Discover all assets in the assets directory and theme assets.

Scans both theme assets (from theme inheritance chain) and site assets (from assets/ directory). Theme assets are discovered first (lower priority), then site assets (higher priority, can override theme assets). Assets are deduplicated by output path with site assets taking precedence.

Parameters 1
assets_dir Path | None

Assets directory path (defaults to root_path/assets). If None, uses site root_path / "assets"
Internal Methods 6
_get_theme_assets_chain
Get theme assets paths in inheritance order (from ThemeIntegrationMixin).
0 list[Path] 
def _get_theme_assets_chain(self) -> list[Path]

Get theme assets paths in inheritance order (from ThemeIntegrationMixin).

Returns

list[Path]

_setup_page_references
Set up page references for navigation (next, prev, parent, etc.). Sets _site a…
0 None 
def _setup_page_references(self) -> None

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

Sets _site and _section references on all pages to enable navigation properties. Must be called after content discovery and section registry building, but before cascade application.

Process:

1. Set _site reference on all pages (including top-level pages)
2. Set _site reference on all sections
3. Set _section reference on section index pages
4. Set _section reference on pages based on their location
5. Recursively process subsections

Build Ordering Invariant:

This method must be called after register_sections() to ensure
the section registry is populated for virtual section URL lookups.

Called By:

discover_content() - Automatically called after content discovery
_setup_section_references
Recursively set up references for a section and its subsections. Sets _site re…
1 None 
def _setup_section_references(self, section: Section) -> None

Recursively set up references for a section and its subsections.

Sets _site reference on subsections, _section reference on index pages, and _section reference on pages within subsections. Recursively processes all nested subsections.

Parameters 1
section Section

Section to set up references for (processes its subsections) Called By: _setup_page_references() - Called for each top-level section
_validate_page_section_references
Validate that pages in sections have correct _section references. Logs warning…
0 None 
def _validate_page_section_references(self) -> None

Validate that pages in sections have correct _section references.

Logs warnings for pages that are in a section's pages list but have _section = None, which would cause navigation to fall back to flat mode.

This validation catches bugs like the virtual section path=None issue described in plan/active/rfc-page-section-reference-contract.md.

Called By:

discover_content() - After _setup_page_references()
_validate_subsection_references
Recursively validate page-section references in subsections.
2 None 
def _validate_subsection_references(self, section: Section, pages_without_section: list[tuple[Page, Section]]) -> None

Recursively validate page-section references in subsections.

Parameters 2
section Section

Section to check subsections of
pages_without_section list[tuple[Page, Section]]

List to append (page, expected_section) tuples to
_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 (like type, version, or visibility) at the section level rather than repeating it on every page.

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