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, plantuml.js, and markmap.js (now under plugins/), plus layouts/_partials/scripts/mermaid.html: override copies made before 0.18 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 site scripts without layout overrides, and converts these three features onto it (#2789).

• If you set params.markmap.enable, params.markmap.version, or params.disable_click2copy_chroma: migrate to the registry, then remove the deprecated parameters. For MarkMap’s migration and legacy behavior, see the MarkMap guide. For the copy button, set enable: false on the click-to-copy entry under params.docsy.plugins.
• If you produce MarkMap markup other than through a markmap fence on the page itself, or print sections that contain one: Docsy’s render hook no longer flags those pages for MarkMap. Set the hasMarkmap page flag from a hooks/head-end.html partial; for the affected authoring paths and the one-line partial, see When a MarkMap doesn’t render.
• If you override a moved file, review and move your override; old copies are silently ignored:
  • assets/js/markmap.js and assets/js/click-to-copy.js moved to assets/js/plugins/.
  • static/js/tabpane-persist.js moved to assets/js/plugins/tabpane-persist.js.
  • scripts/markmap.html is gone; the plugin’s companion partial scripts/plugins/markmap.html takes its role.
• If you override scripts.html, a pre-0.18 copy fails the build (it reads scripts that have moved); 0.18 also decomposed it into a dispatcher over scripts/*.html sub-partials, so take the current file and re-apply your change to the sub-partial it belongs to.
• If you have a project-wide render-codeblock.html hook, it no longer sees markmap fences: Docsy now ships render-codeblock-markmap.html, which takes precedence for that language, as the mermaid, math, and chem hooks already do for theirs.
• If your site config has a params.docsy key of its own, rename it: Docsy now reserves params.docsy for theme settings, and a non-map value there turns the theme plugins off (warnings).
• If your build has no network access or restricts Hugo’s remote fetches, MarkMap builds now fail without cdn.jsdelivr.net: the autoloader is fetched at build time instead of by the browser; for the offline remedy, see MarkMap version.

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→