Module

orchestration.css_optimizer

Content-aware CSS tree shaking.

Analyzes site content to determine which CSS files are needed, then generates an optimized style.css with only necessary imports. This can reduce CSS bundle size by 50%+ for single-purpose sites.

Key Features:

  • Zero external dependencies (pure Python)
  • Automatic detection of content types and features
  • Preserves CSS @layer structure for proper cascade
  • Graceful fallback if no manifest available
  • Full reporting for build output

Usage:

from bengal.orchestration.css_optimizer import CSSOptimizer

optimizer = CSSOptimizer(site)

optimized_css, report = optimizer.generate(report=True)

Or use convenience function

from bengal.orchestration.css_optimizer import optimize_css_for_site css = optimize_css_for_site(site)

See Also:

  • bengal/themes/default/css_manifest.py: Default theme manifest
  • plan/drafted/rfc-css-tree-shaking.md: Design rationale
1Class1Function

Classes

CSSOptimizer 11 ▼
Generates optimized CSS bundles based on site content. **Analyzes pages and sections to detect:** …

Generates optimized CSS bundles based on site content.

Analyzes pages and sections to detect:

  • Content types in use (blog, doc, tutorial, etc.)
  • Features enabled (graph, search, mermaid, etc.)

Then generates a minimal style.css containing only needed imports.

Attributes

Name Type Description
site —

Site instance to analyze
_manifest CSSManifest

Loaded CSS manifest from theme

Methods

get_used_content_types 0 set[str] ▼
Scan site to find all content types in use. **Checks:** - page.metadata.type f…
def get_used_content_types(self) -> set[str]

Scan site to find all content types in use.

Checks:

  • page.metadata.type for each page
  • section.metadata.content_type for each section
Returns
set[str] Set of content type names (e.g., {"blog", "doc"})
get_enabled_features 0 set[str] ▼
Detect features that require CSS. **Checks:** - site.features_detected (popula…
def get_enabled_features(self) -> set[str]

Detect features that require CSS.

Checks:

  • site.features_detected (populated during discovery phase)
  • site.config.features (explicit overrides)
Returns
set[str] Set of feature names (e.g., {"search", "graph"})
get_required_css_files 0 list[str] ▼
Determine which CSS files are needed. **Combines:** - Core CSS (always) - Pale…
def get_required_css_files(self) -> list[str]

Determine which CSS files are needed.

Combines:

  • Core CSS (always)
  • Palettes (all or just active based on config)
  • Shared CSS (always)
  • Type-specific CSS (based on content types)
  • Feature-specific CSS (based on features)
  • Force-include from config
Returns
list[str] Ordered list of CSS file paths (relative to css/ directory)
generate 1 str | tuple[str, CSSOpti… ▼
Generate optimized style.css content. Creates a CSS file with @layer imports c…
def generate(self, report: bool = False) -> str | tuple[str, CSSOptimizationReport]

Generate optimized style.css content.

Creates a CSS file with @layer imports containing only the CSS files needed for the detected content types and features.

Parameters
Name Type Description
report —

If True, also return optimization report

Default:False
Returns
str | tuple[str, CSSOptimizationReport] CSS content string, or tuple of (css_content, report_dict) if report=True
Internal Methods 5 ▼
__init__ 1 ▼
Initialize CSS optimizer.
def __init__(self, site: SiteLike) -> None
Parameters
Name Type Description
site —

Site instance to analyze for content types and features
_load_manifest 0 CSSManifest ▼
Load CSS manifest from theme. Attempts to load the CSS manifest from the activ…
def _load_manifest(self) -> CSSManifest

Load CSS manifest from theme.

Attempts to load the CSS manifest from the active theme. Falls back to empty manifest if theme doesn't have one.

Returns
CSSManifest CSSManifest dictionary with categorized CSS files
_get_theme_dir 1 Any ▼
Get the directory path for a theme.
def _get_theme_dir(self, theme_name: str) -> Any
Parameters
Name Type Description
theme_name —
Returns
Any
_load_manifest_from_path 1 CSSManifest ▼
Load manifest from a Python file path.
def _load_manifest_from_path(self, manifest_path: Any) -> CSSManifest
Parameters
Name Type Description
manifest_path —
Returns
CSSManifest
_get_all_css_files 0 list[str] ▼
Get list of all CSS files in manifest.
def _get_all_css_files(self) -> list[str]
Returns
list[str]

Functions

optimize_css_for_site 1 str ▼
Convenience function to generate optimized CSS.
def optimize_css_for_site(site: SiteLike) -> str
Parameters
Name Type Description
site SiteLike

Site instance
Returns
str