Module

postprocess.speculation

Speculation Rules Generator for Document Applications.

Generates speculation rules JSON for browser prefetching and prerendering. Analyzes site structure to create intelligent prefetch/prerender hints.

The Speculation Rules API enables browsers to prefetch or prerender pages before user navigation, providing near-instant page loads.

Browser Support (as of Dec 2025):

  • Chrome 121+, Edge 121+, Opera 107+ (74% global support)
  • Safari: experimental flag only
  • Firefox: gracefully ignores (no errors)

@see https://developer.chrome.com/docs/web-platform/prerender-pages/

2Classes1Function

Classes

SpeculationRule 4 ▼
A single speculation rule for prefetch or prerender.

A single speculation rule for prefetch or prerender.

Attributes

Name Type Description
href_matches list[str]

URL pattern(s) to match
eagerness str

How eagerly to trigger (conservative | moderate | eager)
exclude_selectors list[str]

CSS selectors to exclude from the rule

Methods

to_dict 0 dict[str, Any] ▼
Convert rule to speculation rules JSON format.
def to_dict(self) -> dict[str, Any]
Returns
dict[str, Any]
SpeculationRulesGenerator 8 ▼
Generates speculation rules based on site configuration and structure. The generator can: 1. Use e…

Generates speculation rules based on site configuration and structure.

The generator can:

  1. Use explicit configuration from bengal.yaml
  2. Auto-generate rules based on site analysis
  3. Combine both approaches

Example config in bengal.yaml: document_application: speculation: enabled: true prerender: eagerness: moderate patterns:

  • "/docs/*"
  • "/blog/*" 
    prefetch:

    eagerness: conservative

    patterns:
  • "/*" 
    exclude_patterns:
  • "/admin/*"
  • "*.pdf"

Methods

is_enabled 0 bool ▼
Check if speculation rules are enabled.
def is_enabled(self) -> bool
Returns
bool
generate 0 dict[str, Any] ▼
Generate the complete speculation rules JSON.
def generate(self) -> dict[str, Any]
Returns
dict[str, Any] Dictionary suitable for JSON serialization as <script type="speculationrules">
to_json 1 str ▼
Generate speculation rules as JSON string.
def to_json(self, indent: int | None = 2) -> str
Parameters
Name Type Description
indent —

JSON indentation level (None for compact)

Default:2
Returns
str JSON string for <script type="speculationrules">
Internal Methods 5 ▼
__init__ 1 ▼
Initialize the speculation rules generator.
def __init__(self, site: SiteLike)
Parameters
Name Type Description
site —

The Bengal site instance
_get_speculation_config 0 dict[str, Any] ▼
Get speculation configuration with defaults.
def _get_speculation_config(self) -> dict[str, Any]
Returns
dict[str, Any]
_create_rule 2 SpeculationRule ▼
Create a speculation rule with standard exclusions.
def _create_rule(self, patterns: list[str], eagerness: str = 'conservative') -> SpeculationRule
Parameters
Name Type Description
patterns —
eagerness — Default:'conservative'
Returns
SpeculationRule
_auto_generate_rules 0 dict[str, list[Speculati… ▼
Auto-generate speculation rules based on site analysis. **Analyzes:** - High-t…
def _auto_generate_rules(self) -> dict[str, list[SpeculationRule]]

Auto-generate speculation rules based on site analysis.

Analyzes:

  • High-traffic navigation paths
  • Content relationships
  • Section structure
Returns
dict[str, list[SpeculationRule]] Dictionary with 'prerender' and 'prefetch' rule lists
_analyze_sections 0 dict[str, dict[str, Any]] ▼
Analyze site sections for speculation rules.
def _analyze_sections(self) -> dict[str, dict[str, Any]]
Returns
dict[str, dict[str, Any]] Dictionary mapping section paths to analysis info

Functions

generate_speculation_rules 1 str ▼
Convenience function to generate speculation rules JSON.
def generate_speculation_rules(site: SiteLike) -> str
Parameters
Name Type Description
site SiteLike

The Bengal site instance
Returns
str