Module

rendering.pipeline.output

Output handling utilities for the rendering pipeline.

This module provides the final stage of the rendering pipeline: determining output paths, selecting templates, and writing rendered HTML to disk.

Key Functions:

  • determine_output_path(): Compute output file path for a page
  • determine_template(): Select template based on page type and metadata
  • write_output(): Write rendered HTML with atomic writes and caching
  • format_html(): Apply HTML minification or pretty-printing
  • embed_content_hash(): Embed content hash in HTML meta tag
  • extract_content_hash(): Extract content hash from HTML

Write Strategies:

The module supports two write modes controlled bybuild.fast_writes:

  • Atomic writes (default): Crash-safe using temporary files and rename. Slightly slower but ensures output is never corrupted on interruption.

  • Fast writes: Direct file writes without atomicity. Used by dev server for maximum performance during rapid iteration.

Content Hash Embedding (RFC: Output Cache Architecture): HTML pages include a content hash meta tag for accurate change detection. This enables the ReloadController to detect meaningful content changes vs regeneration noise, reducing unnecessary hot reloads.

Directory Caching:

Uses thread-safe directory tracking to minimize syscalls during parallel builds. Once a directory is created, subsequent pages skip the exists check.

Related Modules:

  • bengal.rendering.pipeline.core: Main pipeline orchestration
  • bengal.rendering.pipeline.thread_local: Directory creation tracking
  • bengal.utils.url_strategy: URL and path computation
  • bengal.utils.io.atomic_write: Atomic file operations
  • bengal.postprocess.html_output: HTML formatting implementation
8Functions

Functions

determine_output_path 2 Path ▼
Determine the output path for a page. Delegates path computation to centralize…
def determine_output_path(page: PageLike, site: SiteLike) -> Path

Determine the output path for a page.

Delegates path computation to centralized URLStrategy (i18n-aware).

Parameters
Name Type Description
page PageLike

Page to determine path for
site SiteLike

Site instance
Returns
Path
determine_template 1 str ▼
Determine which template will be used for this page. **Template resolution ord…
def determine_template(page: PageLike) -> str

Determine which template will be used for this page.

Template resolution order:

  1. page.template attribute
  2. page.metadata['template']
  3. Default based on page type
Parameters
Name Type Description
page PageLike

Page object
Returns
str
write_output 5 None ▼
Write rendered page to output directory. **Handles:** - Directory creation wit…
def write_output(page: PageLike, site: SiteLike, collector: OutputCollector | None = None, write_behind: WriteBehindCollector | None = None, build_cache: Any = None) -> None

Write rendered page to output directory.

Handles:

  • Directory creation with caching (reduces syscalls)
  • Atomic writes for crash safety (optional)
  • Fast writes for dev server performance
  • Source→output tracking for incremental cleanup
  • Output tracking for hot reload (when collector provided)
  • Write-behind async I/O (when write_behind provided)

RFC: rfc-path-to-200-pgs (Phase III - Write-Behind I/O)

Parameters
Name Type Description
page PageLike

Page with rendered content
site SiteLike

Site instance for config
collector OutputCollector | None

Optional output collector for hot reload tracking

Default:None
write_behind WriteBehindCollector | None

Optional write-behind collector for async writes

Default:None
build_cache Any

Optional BuildCache for direct cache access.

Default:None
_copy_notebook_source 1 None ▼
Copy notebook .ipynb to output directory for download link.
def _copy_notebook_source(page: PageLike) -> None
Parameters
Name Type Description
page PageLike
_track_and_record 4 None ▼
Track output mapping and record output (shared by sync and async paths).
def _track_and_record(page: PageLike, site: SiteLike, collector: OutputCollector | None, build_cache: Any = None) -> None
Parameters
Name Type Description
page PageLike

Page with output_path set
site SiteLike

Site instance
collector OutputCollector | None

Optional output collector for hot reload
build_cache Any

Optional BuildCache for direct cache access.

Default:None
format_html 3 str ▼
Format HTML output (minify/pretty) with content hash embedding. RFC: Output Ca…
def format_html(html: str, page: PageLike, site: SiteLike) -> str

Format HTML output (minify/pretty) with content hash embedding.

RFC: Output Cache Architecture - Content hash is computed BEFORE formatting to ensure deterministic results. This enables accurate change detection.

RFC: rfc-build-performance-optimizations - fast_mode skips formatting entirely.

Respects page-level and site-level configuration:

  • site.config.build.fast_mode: Skip formatting (highest priority)
  • page.metadata.no_format: Skip formatting
  • site.config.html_output.mode: 'minify', 'pretty', or 'raw'
  • site.config.minify_html: Option
  • site.config.build.content_hash_in_html: Embed content hash (default: true)
Parameters
Name Type Description
html str

Rendered HTML content
page PageLike

Page being rendered
site SiteLike

Site instance for config
Returns
str
embed_content_hash 2 str ▼
Embed content hash in HTML using safe template-aware insertion. RFC: Output Ca…
def embed_content_hash(html: str, content_hash: str | None = None) -> str

Embed content hash in HTML using safe template-aware insertion.

RFC: Output Cache Architecture - Embeds a content hash meta tag in the

section for accurate change detection during hot reload.

Handles edge cases:

  • Missing tag → skip embedding (don't break output)
  • Uppercase/whitespace variants → normalize matching
  • Already has hash → update existing
Parameters
Name Type Description
html str

HTML content to embed hash into
content_hash str | None

Pre-computed hash (if None, computes from html)

Default:None
Returns
str
extract_content_hash 1 str | None ▼
Extract content hash from HTML meta tag. RFC: Output Cache Architecture - Extr…
def extract_content_hash(html: str) -> str | None

Extract content hash from HTML meta tag.

RFC: Output Cache Architecture - Extracts embedded content hash for comparison during hot reload change detection.

Returns None if no hash found (old/external content). Handles case-insensitive matching and attribute order variations.

Parameters
Name Type Description
html str

HTML content to extract hash from
Returns
str | None