# 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. A plugin registry carries Mermaid and more; jQuery is gone; doc-rooted sites can publish llms.txt.

---

Site [llms.txt](/fr/llms.txt)

---

<!-- markdownlint-disable descriptive-link-text no-space-in-emphasis -->

<div class="td-card card border me-4">
<div class="card-header">
      Highlights
    </div>
<div class="card-body">
    <p class="card-text">
        

- <i class="fa-solid fa-house text-info fa-lg"></i> <span>[New org, new home](#org-move):
  [`github.com/docsy`][docsy-org], a [Linux Foundation][] project</span>
- <i class="fa-solid fa-plug text-warning fa-lg"></i> <span>[Hello, plugins!](#plugins) Script
  config made easy</span>
- <i class="fa-solid fa-feather text-primary fa-lg"></i> <span>[Bye, jQuery!](#jquery) Lighter,
  faster-starting pages</span>
- <i class="fa-solid fa-robot text-success fa-lg"></i> <span>[Improved agent support:](#llms-txt)
  `llms.txt` for doc-rooted sites, and v2 discovery links</span>

</p>
      </div>
  </div>


## Release summary

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

## Ready to upgrade? <a id="breaking-changes"></a>

- :warning: Respect the [order of steps][] to avoid breaking your build.
- Review <span class="badge text-bg-warning rounded-pill text-small">BREAKING</span> changes:
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Docsy has a new home](#org-move)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Plugins: scripts and settings moved](#plugins)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Mermaid](#mermaid)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [jQuery dropped](#jquery)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i>
    [`llms.txt`: generic template overrides](#llms-txt-actions), if your project
    has one
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Hugo 0.166.0](#hugo),
    and its [upgrade guide][hugo-upgrade] if you build with an older Hugo
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i>
    [Script-dependency versions you set](#script-dep-pins-actions)
- Optionally skim:
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> [Plugins: a registry for site scripts](#plugins)
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> [`llms.txt` for doc-rooted sites](#llms-txt)
  - [Default script-dependency versions](#script-dep-pins), and
    [for maintainers](#for-maintainers)
- <i class="fa-solid fa-rocket text-primary px-1"></i> Jump to [Upgrade to 0.18.0](#upgrade)
  yourself, or [ask an AI agent](#upgrading-with-ai).

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Docsy has a new home: `docsy/docsy` {#org-move}

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

- Theme: [github.com/docsy/docsy][repo]
- Example site: [github.com/docsy/docsy-example][example-repo]

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 {#org-move-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **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] npm package is unaffected.

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

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Plugins {#plugins}

Docsy 0.18 introduces [**plugins**][ug-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][ug-plugin-authoring] (experimental).

### Registry and overrides {#plugins-registry}

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 {#plugins-actions}

#### Registry and overrides {#plugins-actions-registry}

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i> **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`][ug-plugins]; an exact
  `X.Y.Z` is recommended ([warnings][ug-plugins-warnings]).
- For a script of your own, add an entry and the files it names ([Add a custom
  script][ug-plugin-authoring], experimental).

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **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`][ug-plugins] (if you had `true`), then remove the old
  key.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** you override a moved file: old copies are
silently ignored.

- [Review and move your override][update-overrides]:
  - `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](#mermaid-actions)).

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][ug-plugins-warnings]).

- Rename your key.

#### MarkMap {#plugins-actions-markmap}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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`][ug-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][markmap-version]); a range or operator now
    fails the build, as for [Mermaid](#mermaid-actions).

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][markmap-not-rendering].

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][markmap-activating]).

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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`.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][markmap-version].

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Mermaid

Mermaid is now a [plugin](#plugins): 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][ug-plugin-authoring], experimental).

### Now a plugin {#mermaid-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][ug-mermaid-12] section.

### Actions {#mermaid-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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`][ug-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][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][ug-plugins-warnings]).
  - `enable`, unused since Docsy 0.6.0: delete it.
  - Mermaid settings (`theme`, `flowchart.diagramPadding`, …): move to the
    entry's `options` string ([Mermaid settings][mermaid-settings]). Settings it
    dropped (`htmlLabels`, most `class.*` settings) or mangled (`secure`,
    `flowchart.htmlLabels`) now take effect, so rendering may change.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][mermaid-version]).

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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`.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> jQuery dropped {#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.

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 {#jquery-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your own scripts rely on the jQuery that
Docsy loaded. Either:

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

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **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.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> `llms.txt`: doc-rooted sites and agent discovery {#llms-txt}

[Doc-rooted sites][ug-doc-rooted] can now publish [`llms.txt`][ug-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][llmstxt]'s v2
discovery link ([discovery][ug-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 {#llms-txt-actions}

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i> **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][ug-doc-rooted]); to customize the file, see [customize
  output][ug-llms-customize].

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i> **Applies if** your site publishes `llms.txt` and overrides
`head.html`.

- Add the discovery link to your copy ([discovery][ug-discovery]).

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][ug-llms-customize]).

## Default script-dependency versions {#script-dep-pins}

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

| Dependency                         | Pinned version               | Version param                          |
| ---------------------------------- | ---------------------------- | -------------------------------------- |
| [KaTeX][katex-docs]                | 0.18.9   | `params.katex.version`                 |
| [markmap-autoloader][markmap-docs] | 0.18.12 | `params.docsy.plugins.markmap.version` |
| [Mermaid][mermaid-docs]            | 11.17.2 | `params.docsy.plugins.mermaid.version` |
| [Redoc][redoc-docs]                | 2.5.4   | `params.redoc.version`                 |

### Actions {#script-dep-pins-actions}

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **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 {#hugo}

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][hugo-upgrade] has the gates and actions.

### Actions {#hugo-actions}

**Applies to all sites.**

- Upgrade to Hugo 0.166.0: work through the [Hugo
  0.165+ upgrade guide][hugo-upgrade], then [Update Hugo][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][CL@0.18.0] itemizes them.

- **Workflow security**: PRs into `main` are now gated on a [zizmor][] scan of
  the GitHub Actions workflows ([maintainer notes][maintainer-notes-zizmor]).
- **Dependency updates**: Renovate's GitHub Actions bumps now come from GitHub
  Releases and are SHA-pinned ([maintainer notes][maintainer-notes-deps]).
- **Branch model**: the release procedure is now written down against the
  rulesets that enforce it ([branch model][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][maintainer-notes-links]).

## <i class="fa-solid fa-rocket text-primary px-1"></i> Upgrade to 0.18.0 {#upgrade}

Follow [Update Docsy][] and as you do:



<!-- prettier-ignore -->
- :warning: 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](#org-move) **as** you update the theme: the 0.18.0 module path is
  `github.com/docsy/docsy/theme`.
- Use these [supported versions][official support policy]:
  - **[Docsy][update-theme]**: [0.17.0][] -> [0.18.0][]
  - **[Hugo][update-hugo]**: [0.164.0][hugo-0.164.0] ->
    [0.166.0][hugo-supported-version] (theme minimum
    [0.160.1][hugo-min-version], unchanged); for its
    changes, see the [Hugo 0.165+ upgrade guide][hugo-upgrade]
  - **[Node][update-node]**: LTS 24 (unchanged)
  - **[Dart Sass][install-sass]**: 1.102.0 -> 1.105.0
    (`sass-embedded`, on npm-based sites)
- [Review your theme overrides][update-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.
  - <details>
    <summary>Theme files reworked in 0.18.0</summary>

    **Moved**, an old copy silently ignored
    ([Plugins actions](#plugins-actions-registry)):

    - `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](#plugins-actions-registry),
    [Mermaid 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`](#llms-txt)):

    - `index.llms.txt`, to `all.llms.txt`

    **Now live**, a project copy that was ignored before ([Plugins
    actions](#plugins-actions-registry)):

    - `_partials/algolia/head.html` and `_partials/scripts/algolia.html`

    **Takes precedence** ([MarkMap actions](#plugins-actions-markmap)):

    - `_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][repo]:

    ```sh
    git diff --name-status v0.17.0 v0.18.0 -- theme/layouts theme/assets theme/static theme/i18n theme/data
    ```
    </details>

### <i class="fa-solid fa-robot text-info px-1"></i> Upgrading with AI?

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

<section class="td-checkbox-list-wrapper">

### <i class="fa-solid fa-square-check text-primary px-1"></i> Sanity checks

In addition to the [generic site checks][check], 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](#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](#plugins-actions-markmap).
- [ ] If your site uses Mermaid, diagrams render in light and dark mode; see
      [Mermaid](#mermaid).
- [ ] If your project has any LLMS template, the root `llms.txt` renders from
      the one you intend for it ([`llms.txt`](#llms-txt)).
- [ ] The build reports no `params.mermaid` or `params.markmap` error and no
      `docsy-c2c-legacy` warning (settings left under the old keys), and no
      `docsy-config` warning (a malformed `params.docsy` entry; see the user
      guide's [warnings][ug-plugins-warnings]).
- [ ] 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` ([review your theme
      overrides][update-overrides]).
- [ ] 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 deferred same-origin entries; the plugin script tags
        moved.
  - [ ] 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 (with an overridden `head.html`, once you add
        it: [actions](#llms-txt-actions)), the agent directive's wording
        changed, and each Markdown version carries a `Site llms.txt` line after
        its title and description; a site without `llms.txt` loses that line and
        its separator (see [`llms.txt`](#llms-txt)).

</section>

## What's next?

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

<!-- prettier-ignore -->
> [!INFO]- Your opinion counts!
>
> - <i class="fa-solid fa-thumbs-up text-success px-1"></i> If you'd like a feature or fix to be
>   considered for inclusion in an upcoming release, **upvote** (with a thumbs up)
>   the associated issue or PR.
>
> - <i class="fa-solid fa-star text-warning px-1"></i> If you find Docsy useful, consider [starring
>   the repository][star-the-repo] to show your support.
{._list-unstyled}

## References

About this release:

- Changelog entry for [0.18.0][CL@0.18.0]
- Release page for [0.18.0][]
- [Release 0.18.0 preparation issue (#2775)][#2775]
- Git history since [0.17.0][compare-0.17.0]

<!-- prettier-ignore-start -->
[#2775]: https://github.com/docsy/docsy/issues/2775
[#2789]: https://github.com/docsy/docsy/issues/2789
[0.17.0]: https://github.com/docsy/docsy/releases/tag/v0.17.0
[0.18.0]: https://github.com/docsy/docsy/releases/tag/v0.18.0
[0.19.0 milestone]: https://github.com/docsy/docsy/milestone/28
[branch-model]: /project/build/git-repo/#branch-model
[check]: /docs/update/#check
[CL@0.18.0]: /project/about/changelog/#next
[compare-0.17.0]: https://github.com/docsy/docsy/compare/v0.17.0...main
[docsy-org]: https://github.com/docsy
[example-repo]: https://github.com/docsy/docsy-example
[experimental]: /project/about/changelog/#experimental
[head-end]: /docs/content/lookandfeel/#add-code-to-head-or-before-body-end
[hugo-0.164.0]: https://github.com/gohugoio/hugo/releases/tag/v0.164.0
[hugo-min-version]: <https://github.com/gohugoio/hugo/releases/tag/v0.160.1>
[hugo-supported-version]: <https://github.com/gohugoio/hugo/releases/tag/v0.166.0>
[hugo-upgrade]: hugo-0.165.0+/
[install-sass]: /docs/get-started/docsy-as-module/installation-prerequisites/#install-dart-sass
[jQuery]: https://jquery.com/
[jquery-releases]: https://releases.jquery.com/
[katex-docs]: /docs/content/diagrams-and-formulae/#katex-version
[link-cache]: https://github.com/chalin/link-cache
[Linux Foundation]: https://www.linuxfoundation.org/
[llmstxt]: https://llmstxt.org/
[maintainer-notes-deps]: /project/about/maintainer-notes/#dependency-updates
[maintainer-notes-links]: /project/about/maintainer-notes/#link-checking-and-the-link-cache
[maintainer-notes-zizmor]: /project/about/maintainer-notes/#workflow-security-analysis
[markmap-activating]: /docs/content/diagrams-and-formulae/#activating-markmap-support
[markmap-docs]: /docs/content/diagrams-and-formulae/#markmap-version
[markmap-not-rendering]: /docs/content/diagrams-and-formulae/#when-a-markmap-doesnt-render
[markmap-version]: /docs/content/diagrams-and-formulae/#markmap-version
[mdn-dom]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/DOM_scripting
[mermaid-docs]: /docs/content/diagrams-and-formulae/#mermaid-version
[mermaid-settings]: /docs/content/diagrams-and-formulae/#mermaid-settings
[mermaid-version]: /docs/content/diagrams-and-formulae/#mermaid-version
[npm-package]: https://www.npmjs.com/package/@docsy/theme
[official support policy]: /project/about/changelog/#official-support
[order of steps]: /docs/update/#update-order
[redoc-docs]: /docs/content/shortcodes/#redoc
[repo]: https://github.com/docsy/docsy
[star-the-repo]: https://github.com/docsy/docsy
[ug-discovery]: /docs/content/agent-support/#discovery
[ug-doc-rooted]: /docs/content/adding-content/#agent-support
[ug-llms-customize]: /docs/content/agent-support/#customize-output
[ug-llms-txt]: /docs/content/agent-support/#llms-txt
[ug-mermaid-12]: /docs/content/diagrams-and-formulae/#mermaid-12
[ug-plugin-authoring]: /docs/content/plugins/#add-a-custom-script
[ug-plugins]: /docs/content/plugins/
[ug-plugins-warnings]: /docs/content/plugins/#warnings
[ug-script-dep-versions]: /docs/content/diagrams-and-formulae/#script-dep-versions
[Update Docsy]: /docs/update/
[update-hugo]: /docs/update/#update-hugo
[update-node]: /docs/update/#update-node
[update-overrides]: /docs/update/#update-overrides
[update-theme]: /docs/update/#update-theme
[ydnj]: https://github.com/camsong/You-Dont-Need-jQuery
[zizmor]: https://docs.zizmor.sh/
<!-- prettier-ignore-end -->