Release 0.18.0 report and upgrade guide

Release summary

FIXME: two-level map of the post.

Ready to upgrade?

FIXME: triage list + version table (Docsy 0.17.0 -> 0.18.0).

Docsy no longer loads jQuery

Docsy’s own scripts now use standard DOM APIs, so the theme no longer loads jQuery: the jQuery script element is gone from the page head, and window.jQuery and $ are no longer available to site scripts (#1436). Each page makes one fewer third-party request, and sites aiming to serve only local resources have one fewer exception to manage.

What this means for your site:

• No action needed if your project scripts don’t use jQuery. To check, search your project’s own scripts (assets/, layouts/, static/) for $( or jQuery – and in JS files, $. too (in layouts that token is ordinary Hugo template syntax, but do eyeball any inline <script> blocks there).
• If you override a converted file, review your override against the new theme version. The files that changed:
  • assets/js/base.js, search.js, offline-search.js, and plantuml.js, plus assets/js/plugins/markmap.js (moved in 0.18 from assets/js/markmap.js) and layouts/_partials/scripts/mermaid.html: old copies still expect the jQuery that Docsy no longer loads.
  • layouts/_partials/head.html: an old copy keeps loading jQuery – and can mask stale copies of the files above from the console check below.
• If your own scripts rely on the jQuery that Docsy loaded, either:

  • Convert them to standard DOM APIs – for equivalents, see You might not need jQuery, or

  • Keep jQuery by loading it yourself: add the following script element to a hooks/head-end.html partial in your project:

    <script
      src="https://code.jquery.com/jquery-3.7.1.min.js"
      integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g=="
      crossorigin="anonymous"
    ></script>
    

After upgrading, spot-check your key pages – including a diagram page, if your site has them – with the browser console open, and exercise interactive features such as search: a $ is not defined or similar jQuery-is-missing error indicates remaining jQuery-dependent code.

Markmap, tab persistence, and click-to-copy are now plugins

Docsy 0.18 introduces plugins (params.docsy.plugins), a registry for loading scripts without layout overrides, and converts its first three features onto it: markmap, tab-pane persistence, and the code-block copy button. Disabled integrations now ship zero bytes, markmap and tab persistence load only on pages that use them, and every emitted script is fingerprinted with SRI (#2791).

What this means for your site:

• No action needed if you don’t override the affected files. The legacy params.markmap.enable still works for this release cycle – with a build warning, and keeping its pre-0.18 site-wide loading; to enable MarkMap the new way, see the user guide.
• If you override a moved file, review and move your override. The moves: assets/js/markmap.js and assets/js/click-to-copy.js to assets/js/plugins/; static/js/tabpane-persist.js to assets/js/plugins/tabpane-persist.js. Old copies are silently ignored. The partials scripts/markmap.html and scripts/tabpane-persist.html are gone, and scripts/code-copy.html is replaced by scripts/prism.html plus the click-to-copy plugin; stale scripts.html or scripts/main-bundle.html overrides fail the build on the removed bundle members.
• If you override the tabpane shortcode or markmap code-block rendering, refresh your copy: page gating keys on Store flags (hasTabs, hasMarkmap) that only the current templates set – a stale copy silently stops loading the corresponding script.
• If your site restricts Hugo’s remote fetches (security.http), allow cdn.jsdelivr.net: with markmap enabled, builds now fetch the autoloader at build time and serve it from your site, as Mermaid and KaTeX builds already do.

What’s next

FIXME.

References

• Changelog entry for 0.18.0
• Docsy 0.18.0 release page
• Release-prep tracker: FIXME
• Changes since 0.17.0

• ←Previous
• Next→