orchestration.render

Initialize render orchestrator.

Build pages sequentially.

Build pages in parallel for better performance.

Threading Model:

• Creates ThreadPoolExecutor with max_workers threads
• max_workers comes from config (default: 4)
• Each thread gets its own RenderingPipeline instance (cached)
• Each pipeline gets its own MarkdownParser instance (cached)

Free-Threaded Python Support (PEP 703):

• Automatically detects Python 3.13t+ with GIL disabled
• ThreadPoolExecutor gets true parallelism (no GIL contention)
• ~1.5-2x faster rendering on multi-core machines
• No code changes needed - works automatically

Caching Strategy:

Thread-local caching at two levels:
1. RenderingPipeline: One per thread (Jinja2 environment is expensive)
2. MarkdownParser: One per thread (parser setup is expensive)

This means with max_workers=N:

• N RenderingPipeline instances created
• N MarkdownParser instances created
• Both are reused for all pages processed by that thread

Performance Example:

With 200 pages and max_workers=10:

• 10 threads created

• 10 pipelines created (one-time cost: ~50ms)

• 10 parsers created (one-time cost: ~100ms)

• Each thread processes ~20 pages

• Per-page savings: ~5ms (pipeline) + ~10ms (parser) = ~15ms

• Total savings: ~3 seconds vs creating fresh for each page

  On free-threaded Python (3.14t):

• Same setup but ~1.78x faster due to true parallelism

• 1000 pages in 1.94s vs 3.46s with GIL (515 vs 289 pages/sec)

Parallel rendering without progress (traditional).

Render pages sequentially with rich progress bar.

Render pages in parallel with live progress manager.

Render pages in parallel with rich progress bar.

Pre-set output paths for specific pages before rendering.

Only processes pages that are being rendered, not all pages in the site. This is an optimization for incremental builds where we only render a subset.