Navigation And HTML Injection

Module: thornforge.buildsite.nav

Overview

Navigation helpers build the top-nav placeholder and normalize HTML documents so shared CSS, JavaScript, navigation, and info-page wrappers can be inserted idempotently.

Autodoc

HTML rewriting helpers for injecting ThornForge navigation and assets.

These functions normalize generated HTML enough that shared CSS, JavaScript, navigation placeholders, and content wrappers can be inserted consistently even when the source HTML is incomplete or fragmentary.

thornforge.buildsite.nav.build_site_nav_placeholder_html(root_prefix: str, *, current_path: str, current_label: str | None = None) → str

Build the placeholder element consumed by the runtime top-nav script.

Parameters:

• root_prefix – Relative path from the current page back to the site root.

• current_path – Site-relative path of the current page.

• current_label – Optional precomputed label to display in the nav metadata.

Returns:

HTML string for a <nav> placeholder whose data attributes are later read by assets/scripts/top-nav.js.

thornforge.buildsite.nav.inject_document_assets(document: str, stylesheet_hrefs: list[str], script_srcs: list[str]) → str

Ensure an HTML document references the requested CSS and JS assets.

Parameters:

• document – Existing HTML document or fragment to modify.

• stylesheet_hrefs – Asset-relative stylesheet URLs that must be linked from the document.

• script_srcs – Asset-relative script URLs that must be loaded by the document.

Returns:

Updated HTML text containing the requested stylesheet links and script tags exactly once, with missing head or body sections created as needed.

thornforge.buildsite.nav.wrap_info_html_document(document: str, root_prefix: str, *, title: str, current_path: str) → str

Wrap arbitrary HTML or fragments in ThornForge’s shared page shell.

Parameters:

• document – Existing HTML document or fragment to normalize.

• root_prefix – Relative prefix from the current page back to the site root, used for asset URLs.

• title – Title text to inject when the document does not already define one.

• current_path – Site-relative path for the page, used in the navigation placeholder.

Returns:

Fully wrapped HTML document text that includes shared assets, a top-nav placeholder, and a main.info-page__content container.