Script loading

Mon, 01 Jan 0001 00:00:00 +0000

Code-level notes for _partials/scripts/plugins.html, the loop behind params.docsy.plugins. For the architecture and ordering decisions, see the design notes.

Registry contract

params.docsy.plugins is a list of plugin entries:

params:
 docsy:
 plugins:
 - name: NAME # resolves assets/js/plugins/NAME.js
 enable: true # optional; false skips the entry
 defer: true # optional; adds `defer` to the script tag
 pageGate: FLAG # optional; a .Page.Store flag name
 options: {} # optional; reaches the module as @params
 - NAME # bare-name shorthand for { name: NAME }

Names are coerced to strings (printf "%v"): YAML auto-types entries like name: 2048, and the loop must resolve the same asset path either way.
Names are restricted to ^[A-Za-z0-9_-]+$: they address assets and partials by path, so anything that could traverse outside the plugin namespaces is refused with a warning (docsy-plugin-name).
Registry order is emission order.
With pageGate set, the plugin is emitted only on pages carrying the named .Page.Store flag.

Theme-default entries and legacy aliases

The loop appends theme-default entries after the site-declared registry. A site-declared entry of the same name supersedes its auto-registration but inherits the default fields it leaves unset (pageGate, defer); an explicit value, pageGate: '' included, always wins:

ScrollSpy patch

Mon, 01 Jan 0001 00:00:00 +0000

As of Docsy 0.13.0

Summary

Docsy 0.13.0 includes a runtime patch for Bootstrap ScrollSpy that fixes a bug affecting pages with heading IDs that aren’t valid CSS selectors. The patch ensures that active TOC entry tracking works reliably for all pages.

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.

Implementation on Docsy

Script loading

Registry contract

Theme-default entries and legacy aliases

ScrollSpy patch

Problem