This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Implementation

Code-level structure and conventions, Hugo/Docsy templates, SCSS/JS customizations, patches, and internal shims.

This section documents code-level implementation details for the Docsy website, including patches, internal shims, and customizations.

Patches and workarounds

1 - ScrollSpy patch

Runtime patch for Bootstrap ScrollSpy to handle invalid CSS selector IDs.

As of Docsy 0.13.0

Problem

As of Bootstrap 5.3.8 (the version used by Docsy 0.13.0), ScrollSpy fails if a page contains a heading ID that is not also a valid CSS # selector. This can happen, for example, if a heading ID starts with a digit. For technical details about this bug, see #2329.

Solution

Docsy 0.13.0 implements a runtime patch for ScrollSpy that intercepts ScrollSpy’s initialization to properly handle heading IDs starting with digits or containing other characters that form invalid CSS selectors. This allows active TOC entry tracking to work correctly without altering the original heading IDs, so links to headings continue to work as expected.

The patch is automatically applied when ScrollSpy is enabled (which is the default). For implementation details, see #2382, #2383.

Maintenance

CI/CD automatically keeps the patch up-to-date when Bootstrap is updated. The ci:prepare script extracts the method from Bootstrap, applies the patch, and updates the runtime patch file. If the Bootstrap method code has changed to a degree that the patch no longer works, CI will fail, indicating that the patch file needs manual review and updates.

Until the upstream ScrollSpy fix is released in a future Bootstrap version, this patch ensures that active TOC entry tracking works reliably for all pages.

References