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, markmap.js, and plantuml.js, plus 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.

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→