Release 0.18.0 report and upgrade guide

Release summary

• Docsy has a new home!
• Scripts:
  • Plugins: four of Docsy’s optional scripts on one registry; MarkMap now loads only where a map is; plugin authoring (experimental)
  • Mermaid: now a plugin, with early Mermaid 12 support
  • jQuery dropped for lighter, faster-starting pages
  • Default script-dependency versions: Mermaid, MarkMap, KaTeX, and Redoc
• Improved discoverability and support for llms.txt
• Build and project:
  • Hugo 0.166.0: the new supported version, with a companion guide for Hugo’s own changes
  • For maintainers: workflow security analysis, Renovate hardening, branch model, link-cache refresh
• Other notable changes: phone-navbar fix

Ready to upgrade?

• ⚠️ Respect the order of steps to avoid breaking your build.
• Review BREAKING changes:
  • Docsy has a new home
  • Plugins: scripts and settings moved
  • Mermaid
  • jQuery dropped
  • llms.txt: generic template overrides, if your project has one
  • Hugo 0.166.0, and its upgrade guide if you build with an older Hugo
  • Script-dependency versions you set
• Optionally skim:
  • Plugins: a registry for site scripts
  • llms.txt for doc-rooted sites
  • Default script-dependency versions, and for maintainers
• Jump to Upgrade to 0.18.0 yourself, or ask an AI agent.

Docsy has a new home: docsy/docsy

Docsy, created at Google, is now a Linux Foundation project. With the move, the Docsy repositories left the google GitHub organization for their own:

• Theme: github.com/docsy/docsy
• Example site: github.com/docsy/docsy-example

While GitHub redirects the old URLs, Hugo module paths don’t follow redirects. It is good practice to adopt the new canonical paths everywhere.

Actions

Applies if you import Docsy as a Hugo module.

1. Run hugo mod get github.com/docsy/docsy/theme@v0.18.0.
2. In your site config, change the theme’s import path from github.com/google/docsy/theme to github.com/docsy/docsy/theme, whether it’s listed under module.imports or under theme; re-key any module.replacements entry, HUGO_MODULE_REPLACEMENTS value, or go.mod replace directive the same way.
3. Run tidy and pack:
   • hugo mod tidy, which drops the old require line (and hugo mod vendor, if you vendor modules)
   • hugo mod npm pack, which regenerates the dependency entries Docsy’s module contributes to package.json, now keyed by the new path, and their checksum

Applies if you install Docsy from GitHub through npm, a git submodule, or a clone; or your docs link to the old Docsy google organization.

1. Re-point your installation to docsy/docsy:
   • npm: change the docsy spec in package.json from google/docsy to docsy/docsy, then run npm install and, as after every install of the GitHub package, npm run install:theme-deps --prefix node_modules/docsy.
   • Submodule: run git submodule set-url themes/docsy https://github.com/docsy/docsy.git and commit the updated .gitmodules.
   • Clone: run git -C themes/docsy remote set-url origin https://github.com/docsy/docsy.git.
2. Update any documentation URLs, replacing the google org with docsy for links to the Docsy and docsy-example repositories.

The @docsy/theme npm package is unaffected.

For the generic update procedure, which assumes the new path, see Update Docsy.

/ Plugins

Docsy 0.18 introduces plugins (params.docsy.plugins), a registry for loading site scripts from site configuration, and moves four of Docsy’s optional scripts onto it: Mermaid, MarkMap, tab persistence, and click-to-copy (#2789). Each entry takes enable, version, and the plugin’s own options; you can also add a plugin of your own (experimental).

Registry and overrides

The plugin registry replaces the per-feature params.* namespaces and the override points that went with them: each plugin has one entry, one companion partial under scripts/plugins/, and one asset under assets/js/plugins/; the root scripts.html is a dispatcher over sub-partials. Algolia’s two named templates became partials at the same time, and the root baseof.html no longer caches the scripts partial, so page-gated scripts follow each page.

MarkMap

MarkMap now loads only on pages that have a mind map, where enabling it used to load it on every page; and its autoloader is fetched at build time and served from your site, so no inline script remains to hash in a Content Security Policy.

Actions

Registry and overrides

Applies if you want a plugin at a version other than Docsy’s default, or a plugin of your own.

• Set the entry’s version under params.docsy.plugins; an exact X.Y.Z is recommended (warnings).
• For a script of your own, add an entry and the files it names (Add a custom script, experimental).

Applies if you set params.disable_click2copy_chroma. The key is deprecated: a true value is still honored, with a docsy-c2c-legacy build warning, and a false value never had an effect.

• Set enable: false on the click-to-copy entry under params.docsy.plugins (if you had true), then remove the old key.

Applies if you override a moved file: old copies are silently ignored.

• Review and move your override:
  • 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. If you had disabled tab persistence by shipping an empty copy, that no longer works: set enable: false on the tabpane-persist entry instead.
  • scripts/markmap.html and scripts/mermaid.html are gone; each plugin’s companion partial, scripts/plugins/markmap.html and scripts/plugins/mermaid.html, takes its role (for a customized scripts/mermaid.html, see the Mermaid actions).

Applies if your project has layouts/_partials/algolia/head.html or layouts/_partials/scripts/algolia.html (or the legacy layouts/partials/ equivalents). Docsy replaced the algolia/head and algolia/scripts named templates with partials at those paths, so a copy that was silently ignored before 0.18 is an override now.

• Review the copy or remove it.

Applies if you override scripts.html. A pre-0.18 copy fails the build (it reads scripts that have moved); 0.18 also decomposed the file into a dispatcher over scripts/*.html sub-partials.

• Take the current file and re-apply your change to the sub-partial it belongs to.

Applies if your site config has a params.docsy key of its own. Docsy now reserves params.docsy for theme settings, and a non-map value there turns the theme plugins off (warnings).

• Rename your key.

MarkMap

Applies if you set anything under params.markmap. The build fails until the namespace is gone, empty table or map included.

• Move each setting onto the markmap entry under params.docsy.plugins, then delete params.markmap. By key:
  • enable: move to the entry’s enable.
  • version: move to the entry’s version, only if you had overridden the theme’s pin (MarkMap version); a range or operator now fails the build, as for Mermaid.

Applies if you relied on params.markmap.enable loading MarkMap on every page, or produce MarkMap markup other than through a markmap fence on the page itself (tabs, included files, section print views). The registry entry loads MarkMap only on pages Docsy detects a fence on, so those maps stay code blocks with a green build.

• For the one-line remedy (experimental) and the affected authoring paths, see When a MarkMap doesn’t render.

Applies if your own scripts call MarkMap’s API (window.markmap.autoLoader, for example from a body-end hook). The autoloader is now a deferred script.

• Wait for DOMContentLoaded before calling it (Activating MarkMap support).

Applies 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.

• Move any markmap-specific handling into an override of render-codeblock-markmap.html.

Applies 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.

Applies if your Content Security Policy allowed MarkMap’s inline script or style by hash. The autoloader now loads as a same-origin script with no inline block, and the map-sizing style is inserted by script, so a stale style hash shrinks maps silently.

• Allow 'self' for the autoloader, and keep allowing both cdn.jsdelivr.net and unpkg.com: the autoloader still probes both for MarkMap’s libraries.
• Carry the map-sizing rule in a site stylesheet instead of a style hash.

Mermaid

Mermaid is now a plugin: your settings take effect as written (the old params.mermaid translation silently dropped or mangled several), there is no inline script left to hash in a Content Security Policy, and the runtime is a plain Docsy script you can override without touching a layout (plugin files, experimental).

Now a plugin

The Mermaid entry carries the version pin and, as its options string, the mermaid.initialize() object that params.mermaid used to approximate. Docsy starts Mermaid through its run() API from a deferred same-origin script; the pin check lives in the companion partial, the runtime in assets/js/plugins/mermaid.js.

Mermaid 12

Docsy 0.18 supports its Mermaid pin, 11.17.2 (official support policy), and lets you try Mermaid 12 early: set the entry’s version to a 12.x release. Expect Mermaid 12’s own defaults and light and dark renderings that don’t match yet; for the details and where to report, see the user guide’s Mermaid 12 section.

Actions

Applies if you set anything under params.mermaid. The build fails until the namespace is gone, empty table or map included.

• Move each setting onto the mermaid entry under params.docsy.plugins, then delete params.mermaid. By key:
  • version: move to the entry’s version, only if you had overridden the theme’s pin (Mermaid version), and as a plain version string: a range or operator (^11, >=11, *) now fails the build where 0.17 warned; a partial version or tag (11, latest) still builds, with a mermaid-floating-version warning (warnings).
  • enable, unused since Docsy 0.6.0: delete it.
  • Mermaid settings (theme, flowchart.diagramPadding, …): move to the entry’s options string (Mermaid settings). Settings it dropped (htmlLabels, most class.* settings) or mangled (secure, flowchart.htmlLabels) now take effect, so rendering may change.

Applies if you pin a Mermaid version below 10.0.0. Diagrams no longer render: Docsy now starts Mermaid through its run() API.

• Remove your pin to take Docsy’s default, Mermaid 11.17.2 (Mermaid version).

Applies if you customized scripts/mermaid.html. Your copy is ignored; its content splits three ways.

• Re-apply a changed pin check to the companion partial scripts/plugins/mermaid.html.
• Move runtime changes (start, dark mode) to assets/js/plugins/mermaid.js (overriding it is experimental).
• Move settings to the entry’s options.

Applies if your Content Security Policy allowed Mermaid’s inline script by hash.

• Allow 'self' for the deferred same-origin entry that replaces it; cdn.jsdelivr.net is still needed for the library.

/ jQuery dropped

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.

What every page gains: the removed element was a render-blocking request to code.jquery.com in the page head, so pages now start rendering without waiting on a third-party origin; a first visit fetches about 30 KB (compressed) less; and your site’s third-party footprint shrinks by one host, one fewer exception for sites that aim to serve only local resources.

No action is needed if your project’s own scripts don’t use jQuery; to check, search them (assets/, layouts/, static/, and any inline <script> or page-bundle JS under content/) for $( or jQuery, and JS files for $. too (in layouts, $. is ordinary Hugo template syntax, so inspect only their inline <script> blocks).

Actions

Applies if your own scripts rely on the jQuery that Docsy loaded. Either:

• Convert them to standard DOM APIs (MDN’s DOM scripting guide); for jQuery-to-native equivalents, see You Don’t Need jQuery.
• Keep jQuery by loading it yourself: add the script element for your chosen jQuery release from releases.jquery.com (Docsy loaded 3.7.1; pin the same to keep your scripts’ behavior unchanged) to a hooks/head-end.html partial in your project.

Applies if your Content Security Policy allows code.jquery.com.

• Remove it from script-src, unless you load jQuery yourself.

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.

/ llms.txt: doc-rooted sites and agent discovery

Doc-rooted sites can now publish llms.txt from their docs landing page, the page published at the site root. Pages of sites publishing llms.txt now also carry the llms.txt proposal’s v2 discovery link (discovery). Agent support as a whole is still experimental.

Two more changes apply to every site. The line after a Markdown version’s title and description now reads Site llms.txt, linking the current site’s file, and is omitted when the site publishes none. And the theme’s llms.txt template is now all.llms.txt (was index.llms.txt), so that section pages can render it; a project’s generic LLMS template now renders the root file too.

Actions

Applies if your site is doc-rooted and you want an llms.txt.

• Add LLMS to the docs landing page’s outputs, per language (doc-rooted llms.txt setup); to customize the file, see customize output.

Applies if your site publishes llms.txt and overrides head.html.

• Add the discovery link to your copy (discovery).

Applies if your project has a generic all.llms.txt or list.llms.txt template that must not serve as the root file.

• Add a template that takes precedence for the root file: home.llms.txt on a regular site, TYPE/section.llms.txt on a doc-rooted one, where TYPE is the docs landing page’s type, docs unless it sets one (customize output).

Default script-dependency versions

The scripts and stylesheets Docsy fetches from public CDNs, at build time or in the browser, ship at these pinned versions (why pin):

Actions

Applies if you set any of these version params. Docsy 0.17.0 shipped KaTeX 0.18.4, Mermaid 11.17.0, and Redoc 2.5.3.

• Drop a setting that only restated 0.17.0’s default, so that your site takes this release’s pin (official support policy).

Hugo 0.166.0

Docsy’s supported Hugo version moves from 0.164.0 to 0.166.0 (official support policy). Hugo 0.165.0 and 0.166.0 need no change in Docsy’s templates, but some of their changes can break a site’s own build; the companion Hugo 0.165+ upgrade guide has the gates and actions.

Actions

Applies to all sites.

• Upgrade to Hugo 0.166.0: work through the Hugo 0.165+ upgrade guide, then Update Hugo.

Other notable changes

• Phone navbar: with the light/dark mode menu enabled and a navbar menu that scrolls sideways, phone pages no longer render zoomed out.

For this and all other changes, see the 0.18.0 release page.

For maintainers

Changes in this section affect Docsy maintainers and contributors; the first two also make the theme you depend on harder to compromise. The changelog’s For-maintainers list itemizes them.

• Workflow security: PRs into main are now gated on a zizmor scan of the GitHub Actions workflows (maintainer notes).
• Dependency updates: Renovate’s GitHub Actions bumps now come from GitHub Releases and are SHA-pinned (maintainer notes).
• Branch model: the release procedure is now written down against the rulesets that enforce it (branch model).
• Link cache: docsy.dev’s committed link cache now follows the link-cache package’s format and prune rule, and a scheduled workflow proposes refreshes as PRs (maintainer notes).

Upgrade to 0.18.0

Follow Update Docsy and as you do:

• ⚠️ Respect the order of steps to avoid breaking your build. Tracking main between releases? Some actions may already be applied; check each gate.
• If you import Docsy as a Hugo module, re-point it at Docsy’s new home as you update the theme: the 0.18.0 module path is github.com/docsy/docsy/theme.
• Use these supported versions:
  • Docsy: 0.17.0 -> 0.18.0
  • Hugo: 0.164.0 -> 0.166.0 (theme minimum 0.160.1, unchanged); for its changes, see the Hugo 0.165+ upgrade guide
  • Node: LTS 24 (unchanged)
  • Dart Sass: 1.102.0 -> 1.105.0 (sass-embedded, on npm-based sites)
• Review your theme overrides. Diffing each override against its new counterpart finds the changes in files that kept their place; the moved, replaced, and new files below need a look of their own.
  • Theme files reworked in 0.18.0

    Moved, an old copy silently ignored (Plugins actions):

    • assets/js/click-to-copy.js and assets/js/markmap.js, to assets/js/plugins/
    • static/js/tabpane-persist.js, to assets/js/plugins/

    Replaced (Plugins actions, Mermaid actions):

    • _partials/scripts/markmap.html and mermaid.html, by _partials/scripts/plugins/*.html
    • _partials/scripts.html, now a dispatcher over _partials/scripts/*.html
    • _partials/llms-directive.html, reworded; a copy keeps the old text

    Renamed (llms.txt):

    • index.llms.txt, to all.llms.txt

    Now live, a project copy that was ignored before (Plugins actions):

    • _partials/algolia/head.html and _partials/scripts/algolia.html

    Takes precedence (MarkMap actions):

    • _markup/render-codeblock-markmap.html, a new theme hook that takes markmap fences from a project-wide render-codeblock.html

    New theme files, overrides if your project already has a file at the path:

    • assets/js/plugins/mermaid.js
    • data/docsy/schema/params/docsy.yaml
    • _partials/scripts/main-bundle.html, plantuml-deflate.html, plugins.html, and prism.html
    • _partials/scripts/plugins/, the plugin partials
    • _partials/td/root-page.html
    • _shortcodes/_root-llms-txt-path.html

    For the full list of changed theme files, run the following in a clone of docsy/docsy:

    git diff --name-status v0.17.0 v0.18.0 -- theme/layouts theme/assets theme/static theme/i18n theme/data
    

Upgrading with AI?

Give your assistant this post and the companion Hugo guide as its upgrade instructions; both are written to be followed step by step.

What’s next?

Work towards the next release is tracked under the 0.19.0 milestone.

References

About this release:

• Changelog entry for 0.18.0
• Release page for 0.18.0
• Release 0.18.0 preparation issue (#2775)
• Git history since 0.17.0

• ←Previous
• Next→