sanitize_filename_slug function

Produces a filesystem-safe, cross-platform slug from a logical filename.

Neutralizes every character Windows forbids in a filename (< > : " / \\ | ? *) plus .. traversal, so a malformed entity/namespace name – or an overloaded C++ operator function whose own name IS one of these characters (confirmed crash: operator| produced function_operator|.html, rejected by Windows with Invalid argument during a real Kernel SDK render) – can never produce an illegal or output-directory-escaping path. Kept deliberately minimal so it matches the pre-existing per-family behaviour for every ordinary name and only adds* uniform escaping the per-language _resolve_base_filename hooks don’t already cover (some handle */& themselves for C++ pointer/ reference types; re-escaping here is idempotent, a harmless no-op for characters already gone by the time this runs). A single trailing extension (.html/.md) is preserved and the intentional __ scope separator is left intact.

Also rejects control characters and Windows-reserved device names (CON, COM1, …), and truncates a stem exceeding MAX_COMPONENT_CHARS (measured in UTF-8 bytes, since Linux’s NAME_MAX is a byte limit) to that budget, replacing the cut tail with a deterministic _<8 hex> suffix hashed from the full pre-truncation stem – keeps two long names sharing a prefix from colliding onto the same file, and is idempotent: re-sanitizing an already-truncated stem is a no-op, since it is already at or under budget (required so a second accidental pass through this function – or a second reference to an already-resolved filename – never appends a second suffix and breaks existing links).

Primary-template display names carry their formal parameter list in the entity’s name_suffix (rendered in titles/navigation), never in name, so those characters do not reach this slug at all – display and slug stay decoupled by construction.

Methods

sanitize_filename_slug

sanitize_filename_slug(filename: str) -> str

Produces a filesystem-safe, cross-platform slug from a logical filename.

Neutralizes every character Windows forbids in a filename (< > : " / \\ | ? *) plus .. traversal, so a malformed entity/namespace name – or an overloaded C++ operator function whose own name IS one of these characters (confirmed crash: operator| produced function_operator|.html, rejected by Windows with Invalid argument during a real Kernel SDK render) – can never produce an illegal or output-directory-escaping path. Kept deliberately minimal so it matches the pre-existing per-family behaviour for every ordinary name and only adds* uniform escaping the per-language _resolve_base_filename hooks don’t already cover (some handle */& themselves for C++ pointer/ reference types; re-escaping here is idempotent, a harmless no-op for characters already gone by the time this runs). A single trailing extension (.html/.md) is preserved and the intentional __ scope separator is left intact.

Also rejects control characters and Windows-reserved device names (CON, COM1, …), and truncates a stem exceeding MAX_COMPONENT_CHARS (measured in UTF-8 bytes, since Linux’s NAME_MAX is a byte limit) to that budget, replacing the cut tail with a deterministic _<8 hex> suffix hashed from the full pre-truncation stem – keeps two long names sharing a prefix from colliding onto the same file, and is idempotent: re-sanitizing an already-truncated stem is a no-op, since it is already at or under budget (required so a second accidental pass through this function – or a second reference to an already-resolved filename – never appends a second suffix and breaks existing links).

Primary-template display names carry their formal parameter list in the entity’s name_suffix (rendered in titles/navigation), never in name, so those characters do not reach this slug at all – display and slug stay decoupled by construction.

Generated with Flude

Copyright © 2026