Module

orchestration.section

Section orchestration for Bengal SSG.

Handles section lifecycle: ensuring all sections have index pages, validation, and structural integrity.

View source
1 Class

Classes

SectionOrchestrator
Handles section structure and completeness. Responsibilities: - Ensure all sections have index pag…
13

Handles section structure and completeness.

Responsibilities:

  • Ensure all sections have index pages (explicit or auto-generated)
  • Generate archive pages for sections without _index.md
  • Validate section structure
  • Maintain section hierarchy integrity

This orchestrator implements the "structural" concerns of sections, separate from cross-cutting concerns like taxonomies (tags, categories).

Methods 2

finalize_sections
Finalize sections by ensuring they have index pages. For each section: - If it…
1 None 
def finalize_sections(self, affected_sections: set[str] | None = None) -> None

Finalize sections by ensuring they have index pages.

For each section:

  • If it has an explicit _index.md, leave it alone
  • If it doesn't have an index page, generate an archive page
  • Recursively process subsections

This ensures all section URLs resolve to valid pages.

Parameters 1
affected_sections set[str] | None

Set of section paths that were affected by changes. If None, finalize all sections (full build). If provided, only finalize affected sections (incremental).
validate_sections
Validate that all sections have valid index pages.
0 list[str] 
def validate_sections(self) -> list[str]

Validate that all sections have valid index pages.

Returns

list[str] —

List of validation error messages (empty if all valid)

Internal Methods 11
__init__
Initialize section orchestrator.
1 None 
def __init__(self, site: Site)

Initialize section orchestrator.

Parameters 1
site Site

Site instance to manage sections for
_finalize_recursive_filtered
Recursively finalize only affected sections (incremental optimization).
2 int 
def _finalize_recursive_filtered(self, section: Section, affected_sections: set[str]) -> int

Recursively finalize only affected sections (incremental optimization).

Parameters 2
section Section

Section to finalize
affected_sections set[str]

Set of section paths that were affected
Returns

int —

Number of archive pages created

_needs_finalization
Check if a section or any of its subsections needs finalization. A section nee…
1 bool 
def _needs_finalization(self, section: Section) -> bool

Check if a section or any of its subsections needs finalization.

A section needs finalization if it or any subsection lacks an index page. This is used to ensure sections are finalized even in incremental builds.

Parameters 1
section Section

Section to check
Returns

bool —

True if section or any subsection lacks an index page

_finalize_recursive
Recursively finalize a section and its subsections.
1 int 
def _finalize_recursive(self, section: Section) -> int

Recursively finalize a section and its subsections.

Parameters 1
section Section

Section to finalize
Returns

int —

Number of archive pages created

_detect_content_type
Detect what kind of content this section contains. Delegates to the content ty…
1 str 
def _detect_content_type(self, section: Section) -> str

Detect what kind of content this section contains.

Delegates to the content type registry's detection logic. Respects site-level default_content_type configuration.

Parameters 1
section Section

Section to analyze
Returns

str —

Content type name (e.g., 'blog', 'doc', 'api-reference')

_should_paginate
Determine if section should have pagination. Delegates to the content type str…
2 bool 
def _should_paginate(self, section: Section, content_type: str) -> bool

Determine if section should have pagination.

Delegates to the content type strategy's pagination logic.

Parameters 2
section Section

Section to check
content_type str

Detected content type
Returns

bool —

True if section should have pagination

_get_template_for_content_type
Get the appropriate template for a content type. Delegates to the content type…
1 str 
def _get_template_for_content_type(self, content_type: str) -> str

Get the appropriate template for a content type.

Delegates to the content type strategy's template logic.

Parameters 1
content_type str

Type of content
Returns

str —

Template name

_prepare_posts_list
Prepare the posts list for a section using content type strategy.
2 list[Page] 
def _prepare_posts_list(self, section: Section, content_type: str) -> list[Page]

Prepare the posts list for a section using content type strategy.

Parameters 2
section Section

Section to prepare posts for
content_type str

Content type of the section
Returns

list[Page] —

Filtered and sorted list of pages

_create_archive_index
Create an auto-generated index page for a section. Detects content type and us…
1 Page 
def _create_archive_index(self, section: Section) -> Page

Create an auto-generated index page for a section.

Detects content type and uses appropriate template:

  • API reference docs: api-reference/list.html (no pagination)
  • CLI reference docs: cli-reference/list.html (no pagination)
  • Tutorial sections: tutorial/list.html (no pagination)
  • Blog/chronological: archive.html (with pagination)
  • Generic sections: index.html (fallback)
Parameters 1
section Section

Section that needs an index page
Returns

Page —

Page object representing the section index

_enrich_existing_index
Enrich an existing user-created index page with section context. This adds the…
1 None 
def _enrich_existing_index(self, section: Section) -> None

Enrich an existing user-created index page with section context.

This adds the same metadata that auto-generated archives get, allowing user-created index pages with type: blog or archive to work properly.

Parameters 1
section Section

Section with an existing index page
_validate_recursive
Recursively validate a section and its subsections.
1 list[str] 
def _validate_recursive(self, section: Section) -> list[str]

Recursively validate a section and its subsections.

Parameters 1
section Section

Section to validate
Returns

list[str] —

List of validation error messages