Module

core.site.core

Core Site dataclass for Bengal SSG.

The Site object is the central container for all content (pages, sections, assets) and coordinates discovery, rendering, and output generation. It maintains caches for expensive operations and provides query interfaces for templates.

Key Concepts:

  • Content organization: Pages, sections, and assets organized hierarchically
  • Caching: Expensive property caches invalidated when content changes
  • Theme integration: Theme resolution and template/asset discovery
  • Query interfaces: Taxonomy, menu, and page query APIs for templates

Related Modules:

  • bengal.orchestration.build: Build orchestration using Site
  • bengal.rendering.template_engine: Template rendering with Site context
  • bengal.cache.build_cache: Build state persistence

See Also:

  • plan/active/rfc-incremental-builds.md: Incremental build design
View source
1 Class

Classes

Site dataclass
Represents the entire website and orchestrates the build process. Creation: Recommended: Site.…
7

Represents the entire website and orchestrates the build process.

Creation:

Recommended: Site.from_config(root_path)

  • Loads configuration from bengal.toml

  • Applies all settings automatically

  • Use for production builds and CLI

    Direct instantiation: Site(root_path=path, config=config)

  • For unit testing with controlled state

  • For programmatic config manipulation

  • Advanced use case only

Inherits from SitePropertiesMixin,PageCachesMixin,SiteFactoriesMixin,ThemeIntegrationMixin,ContentDiscoveryMixin,DataLoadingMixin,SectionRegistryMixin

Attributes

Name Type Description
root_path Path

Root directory of the site
config dict[str, Any]

Site configuration dictionary (from bengal.toml or explicit)
pages list[Page]

All pages in the site
sections list[Section]

All sections in the site
assets list[Asset]

All assets in the site
theme str | None

Theme name or path
output_dir Path

Output directory for built site
build_time datetime | None

Timestamp of the last build
taxonomies dict[str, dict[str, Any]]

Collected taxonomies (tags, categories, etc.)
menu dict[str, list[MenuItem]]
menu_builders dict[str, MenuBuilder]
menu_localized dict[str, dict[str, list[MenuItem]]]
menu_builders_localized dict[str, dict[str, MenuBuilder]]
current_language str | None
data Any
_regular_pages_cache list[Page] | None
_generated_pages_cache list[Page] | None
_listable_pages_cache list[Page] | None
_page_path_map dict[str, Page] | None
_page_path_map_version int
_theme_obj Theme | None
_query_registry Any
_section_registry dict[Path, Section]
_section_url_registry dict[str, Section]
_config_hash str | None
_dev_menu_metadata dict[str, Any] | None
_affected_tags set[str]
_page_lookup_maps dict[str, dict[str, Page]] | None
_last_build_stats dict[str, Any] | None
_template_parser Any

Methods 4

build
Build the entire site. Delegates to BuildOrchestrator for actual build process.
12 BuildStats 
def build(self, parallel: bool = True, incremental: bool | None = None, verbose: bool = False, quiet: bool = False, profile: BuildProfile | None = None, memory_optimized: bool = False, strict: bool = False, full_output: bool = False, profile_templates: bool = False, changed_sources: set[Path] | None = None, nav_changed_sources: set[Path] | None = None, structural_changed: bool = False) -> BuildStats

Build the entire site.

Delegates to BuildOrchestrator for actual build process.

Parameters 12
parallel bool

Whether to use parallel processing
incremental bool | None

Whether to perform incremental build (only changed files)
verbose bool

Whether to show detailed build information
quiet bool

Whether to suppress progress output (minimal output mode)
profile BuildProfile | None

Build profile (writer, theme-dev, or dev)
memory_optimized bool

Use streaming build for memory efficiency (best for 5K+ pages)
strict bool

Whether to fail on warnings
full_output bool

Show full traditional output instead of live progress
profile_templates bool

Enable template profiling for performance analysis
changed_sources set[Path] | None
nav_changed_sources set[Path] | None
structural_changed bool

Whether structural changes occurred (file create/delete/move) Forces full content discovery when True.
Returns

BuildStats —

BuildStats object with build statistics

serve
Start a development server.
5 None 
def serve(self, host: str = 'localhost', port: int = 5173, watch: bool = True, auto_port: bool = True, open_browser: bool = False) -> None

Start a development server.

Parameters 5
host str

Server host
port int

Server port
watch bool

Whether to watch for file changes and rebuild
auto_port bool

Whether to automatically find an available port if the specified one is in use
open_browser bool

Whether to automatically open the browser
clean
Clean the output directory by removing all generated files. Useful for startin…
0 None 
def clean(self) -> None

Clean the output directory by removing all generated files.

Useful for starting fresh or troubleshooting build issues.

reset_ephemeral_state
Clear ephemeral/derived state that should not persist between builds. This met…
0 None 
def reset_ephemeral_state(self) -> None

Clear ephemeral/derived state that should not persist between builds.

This method is intended for long-lived Site instances (e.g., dev server) to avoid stale object references across rebuilds.

Persistence contract:

  • Persist: root_path, config, theme, output_dir, build_time
  • Clear: pages, sections, assets
  • Clear derived: taxonomies, menu, menu_builders, xref_index (if present)
  • Clear caches: cached page lists
Internal Methods 3
__post_init__
Initialize site from configuration.
0 None 
def __post_init__(self) -> None

Initialize site from configuration.

_rmtree_robust staticmethod
Remove directory tree with retry logic for transient filesystem errors. Delega…
2 None 
def _rmtree_robust(path: Path, max_retries: int = 3) -> None

Remove directory tree with retry logic for transient filesystem errors.

Delegates to bengal.utils.file_io.rmtree_robust for the actual implementation. This method exists for backward compatibility.

Parameters 2
path Path

Directory to remove
max_retries int

Number of retry attempts (default 3)
__repr__
0 str 
def __repr__(self) -> str
Returns

str