Release 0.18.0 report and upgrade guide

Docsy is now a Linux Foundation project, with its own GitHub organization and a new Hugo module path. Mermaid and friends become plugins you control from site configuration; jQuery is gone; doc-rooted sites can publish llms.txt.
By Patrice Chalin (CNCF), for the Docsy Steering Committee |
Tags:
Highlights

Release summary

Ready to upgrade?

Docsy has a new home: docsy/docsy

Docsy, created by Google and open sourced in 2018, is now a Linux Foundation project, as announced by Erin McKean at the Open Source Summit EU on October 7, 2026.

The project repositories have moved into their new docsy GitHub organization:

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 theme’s npm-dependency workspace from the re-pointed module; then npm install

Applies if you install Docsy from GitHub through npm, a git submodule, or a clone. 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.

Applies if your docs link to the old Docsy google organization.

  • Replace google with docsy in 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: optional scripts you turn on or off, pin, and configure from site configuration, with no layout override. Four of Docsy’s scripts ship as plugins:

You can also add a script of your own (experimental).

Actions

Applies if you override scripts.html.

  • Delete your copy and re-apply your change to the scripts/*.html sub-partial it belongs to; the file is now a dispatcher over them.

Applies if you disabled tab persistence by shipping an empty static/js/tabpane-persist.js. The file moved, so the copy is ignored and persistence is back on.

Applies if your site config sets params.docsy, or params.docsy.plugins, to something other than a map (a string or a list, say). Docsy now reserves params.docsy for theme settings, and a non-map value at either key turns the theme plugins off with a docsy-config warning; the build stays green.

  • Move your value to another key, and update the templates that read it.

Applies if you want a script of your own.

Applies if your site config has keys of its own under params.docsy beside plugins. Docsy ignores them with a docsy-config warning; templates that read them still work.

  • Move them to another key to silence the warning.

Applies if you set params.disable_click2copy_chroma, deprecated.

  • Remove the key; if it was true, set enable: false on the click-to-copy entry to keep the buttons off.

Mermaid

Mermaid is now a plugin: its settings and version pin live on its params.docsy.plugins.mermaid entry.

Actions

Applies if your site config has params.mermaid, even empty: the build fails.

  • Move each setting onto the mermaid entry, then delete params.mermaid. By key:
    • version: move to the entry’s version as a plain X.Y.Z string, only if you had overridden the theme’s pin.
    • enable: delete it.
    • Mermaid settings (theme, flowchart.diagramPadding, …): move to the entry’s options string; settings 0.17 ignored now take effect, so rendering may change.

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.
  • Move settings to the entry’s options.

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

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

Applies if you want to try Mermaid 12 early (experimental).

  • Set the entry’s version to a 12.x release; for what to expect and where to report, see the user guide’s Mermaid 12 section.

MarkMap

MarkMap is now a plugin, and loads only on pages with a mind map; its version pin lives on its params.docsy.plugins.markmap entry.

Actions

Applies if your site config has params.markmap, even empty: the build fails.

  • Move each setting onto the markmap entry, then delete params.markmap. By key:
    • enable: move to the entry’s enable.
    • version: move to the entry’s version as a plain X.Y.Z string, only if you had overridden the theme’s pin.

Applies if you relied on params.markmap.enable loading MarkMap on every page, or your maps come from anywhere but a markmap fence written on the page itself: the tab or readfile shortcodes, content pulled in with .Content, raw HTML, or section print. Docsy now loads MarkMap only on pages whose own fence it renders, so those maps stay code blocks with a green build.

Applies if your own scripts call MarkMap’s API (window.markmap.autoLoader). The autoloader is now a deferred script.

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.

  • Move any markmap-specific handling into an override of render-codeblock-markmap.html, keeping its {{ .Page.Store.Set "hasMarkmap" true }} line: that flag is what loads MarkMap on the page.

Applies if your build restricts Hugo’s remote fetches or has no network access. Docsy now fetches MarkMap’s autoloader at build time, from cdn.jsdelivr.net, where 0.17 left it to the browser.

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

  • Re-apply a changed pin check to the companion partial scripts/plugins/markmap.html.
  • Move autoloader settings and the map-sizing style to assets/js/plugins/markmap.js.

Applies if your Content Security Policy allowed MarkMap’s inline script or style by hash. Both are gone; 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.

/ jQuery dropped

The theme no longer loads jQuery: window.jQuery and $ are gone from every page, and Docsy’s own scripts use standard DOM APIs. Every page loses:

  • A render-blocking request to code.jquery.com in the page head
  • About 30 KB (compressed) on a first visit
  • A third-party dependency

Actions

To determine if your project uses jQuery, search your script files and inline <script> blocks for:

  • $(
  • $.
  • jQuery

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

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

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

/ 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. 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 project has a generic all.llms.txt or list.llms.txt template that must not serve as the root file of a regular (not doc-rooted) site.

  • Add layouts/home.llms.txt, which takes precedence for the root file; for the template’s shape, see customize output.

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

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

Other notable changes

For all 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.

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:
  • Drop a script-dependency version param that only restates a 0.17.0 default, so that your site takes this release’s pin.
  • 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:

      • assets/js/click-to-copy.js and assets/js/markmap.js, to assets/js/plugins/
      • static/js/tabpane-persist.js, to assets/js/plugins/
      • _partials/algolia/scripts.html, the override path 0.17’s search guide named, to _partials/scripts/algolia.html

      Replaced (Mermaid, MarkMap, and Plugins actions):

      • _partials/scripts/markmap.html and mermaid.html, by _partials/scripts/plugins/*.html
      • _partials/scripts.html, now a dispatcher over _partials/scripts/*.html

      Renamed (llms.txt):

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

      Now taking effect, an override Docsy previously ignored:

      • _partials/algolia/head.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; a project file at that path shadows it

      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.

Sanity checks

In addition to the generic site checks, for this release:

  • For a Hugo module, hugo mod graph lists github.com/docsy/docsy/theme at the version you pinned (or your replacement for it) and no github.com/google/docsy entry remains. If you re-pointed an npm-from-GitHub, submodule, or clone install, package.json names docsy/docsy, or git -C themes/docsy remote -v shows the new URL.
  • With the browser console open, your key pages and search show no $ is not defined or similar error; see jQuery.
  • If your site uses MarkMap, tab persistence, or click-to-copy, each still works on every page that had it; for the pages most likely to lose a map, see the MarkMap actions.
  • If your site uses Mermaid, diagrams render in light and dark mode; see Mermaid.
  • If your project has any LLMS template, the root llms.txt renders from the one you intend for it.
  • The build reports no docsy-c2c-legacy warning (a setting left under the old key) and no docsy-config warning (a malformed params.docsy entry).
  • If you pinned a Mermaid or MarkMap version, the build runs without a *-floating-version warning and diagrams render at that version.
  • If you override the root baseof.html, it includes scripts.html with partial, not partialCached.
  • If you diff built output, investigate only differences beyond these expected ones:
    • The jQuery script element is gone from head.
    • Mermaid’s inline module script, and MarkMap’s inline script and style, are replaced by same-origin script entries, MarkMap’s autoloader included; the plugin script tags moved.
    • If you enabled MarkMap, its tags appear only on pages with a map.
    • On pages that use the root baseof.html, script tags follow each page’s own needs (page-gated diagrams and math, a per-page body-end hook) rather than the first-rendered page’s.
    • On sites publishing llms.txt, every page head has a rel="describedby" link, an overridden head.html included once you’ve added it, and the agent directive’s wording changed.
    • Each Markdown version’s line after its title and description reads Site llms.txt; a site without llms.txt loses that line and its separator.

What’s next?

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

References

About this release:

Last modified October 7, 2026: Release 0.18.0 preparation (#2861) (d160eab)