Blog

• Hugo 0.158.0-0.163.x upgrade guide
• Release 0.16.0 report and upgrade guide
• Release 0.15.0 report and upgrade guide
• Release 0.14.0 report and upgrade guide
• Hugo 0.152.0-0.155.x upgrade guide
• Release 0.13.0 report and upgrade guide
• Upgrade to Docsy 0.12.0 from 0.11.0
• Docsy 2024 Review: Adoptions and Enhancements
• Docsy 0.10.0 release report
• Docsy 0.9.0 release report
• Docsy priorities for 2024
• Upgrade to Docsy 0.7 & Bootstrap 5
• Migrating to Bootstrap 5.2
• Hello Docsy!

Hugo 0.158.0-0.163.x upgrade guide

This post summarizes breaking, security, and notable changes in Hugo 0.158.0 to 0.163.2 that are relevant to Docsy users. It is a companion post to the Docsy 0.16.0 release and upgrade guide.

Docsy 0.16.0 requires Hugo 0.158.0 or later. The Docsy project build is tested with Hugo 0.163.2, which is the recommended target for this upgrade range.

Upgrade summary

This guide highlights Hugo changes that may require action when upgrading a Docsy site to 0.16.0.

• Review BREAKING changes:
  • Docsy now requires Hugo 0.158.0 or later
  • Node 22+ is required for Hugo-managed Node tools
  • HTML content and symlink security changed
• Review deprecations:
  • Language config and template APIs
  • Imaging config and template APIs
• Optionally skim:
  • Markdown-link escaping
  • Image URL churn
  • Template and module cleanup
  • Notable changes
• Jump to Upgrade to Hugo 0.163.2 once you’re ready.

Hugo version for Docsy 0.16.0

Docsy 0.16.0 raises the theme’s minimum supported Hugo version from 0.146.0 to 0.158.0. Theme templates now use Hugo language APIs introduced in 0.158.0, so older Hugo versions will fail with template errors.

The theme minimum remains 0.158.0 through the 0.163.x range. However, we recommend upgrading directly to Hugo 0.163.2 because the later releases include security fixes, avoid a short-lived 0.159.x link-escaping regression, and are the versions validated across Docsy, the Docsy example site, and at least one large downstream Docsy site.

Actions

Applies to all sites upgrading to Docsy 0.16.0.

• Upgrade Hugo to 0.158.0 or later. Prefer 0.163.2.

• If your project declares module.hugoVersion.min, set it to at least 0.158.0.

• If you use hugo-extended, pin a compatible version in your site:

  npm install hugo-extended@0.163.2 --save-dev
  

• If you use hvm, select the latest compatible Hugo release:

  hvm use 0.163.2
  

Language API deprecations (0.158.0)

Hugo 0.158.0 renamed several language configuration keys and template methods. The old names log deprecation notices first, then move toward warnings and eventual errors on Hugo’s deprecation timeline.

Docsy’s own templates and docs now use the new names, which is why Docsy 0.16.0 requires Hugo 0.158.0 or later.

Actions

Applies if your multilingual site config uses older language keys. Rename them when convenient:

# OLD
languages:
  en:
    languageName: English
    languageDirection: ltr

# NEW
languages:
  en:
    label: English
    direction: ltr

Applies if your site overrides language-related templates or partials. Review custom template code for these replacements:

For current Docsy examples, see Multi-language support.

Markdown-link escaping (0.159.2 to 0.160.1)

Hugo 0.159.2 included a security fix for dangerous URLs in Markdown links and images. It also introduced a regression that could double-escape & in rendered Markdown link URLs, producing & in HTML output.

Hugo 0.160.0 fixed that regression, and Hugo 0.160.1 is the safer 0.160.x patch release. If you are moving through this range, do not stop at 0.159.2.

Actions

Applies if you briefly tested or deployed Hugo 0.159.2.

• Upgrade to Hugo 0.160.1 or later.
• Search generated HTML for & in link URLs.
• Pay closest attention to monolingual sites without custom link render hooks.

Multilingual single-host sites are usually shielded because Hugo’s useEmbedded: auto behavior activates the embedded link render hook. Sites with custom link render hooks are also usually shielded. The safest path is still to use Hugo 0.160.1 or later.

Template and module cleanup (0.159.x-0.160.x)

Hugo 0.159.x continued several cleanup paths that may show up in older Docsy sites, Docsy forks, or large downstream sites with local template overrides. Hugo 0.160.1 then fixed several rendering issues in this range.

Actions

Applies if your site has custom templates, module mounts, or conversion scripts.

• Replace deprecated site.Data usage with hugo.Data.
• Replace deprecated includeFiles and excludeFiles module mount options with files.
• Replace deprecated :filename permalink placeholders with :contentbasename.
• If you run hugo mod npm pack, test it after upgrading.
• If you use hugo convert, review generated output before committing it.

Applies if your site uses Goldmark passthrough, RenderShortcodes, or multilingual root sections. Prefer Hugo 0.160.1 or later and include these pages in smoke tests. Hugo 0.160.1 fixed relevant regressions around passthrough elements in headings, shortcode rendering context markers, and multilingual root section generation.

Node-managed tools (0.161.x)

Hugo 0.161.x runs Node-based tools such as PostCSS, Babel, and Tailwind under Node’s --permission sandbox. This requires Node 22 or later. Docsy continues to recommend Node LTS 24 for supported builds.

Docsy sites commonly use PostCSS for CSS processing, so this can be a practical breaking change even when the Docsy theme itself has not changed.

Hugo 0.163.2 fixes an ERR_ACCESS_DENIED regression in this permission model that could abort builds when node_modules lives outside the project tree, such as in a CI provider’s shared cache (for example, Netlify). It is another reason to prefer 0.163.2 for PostCSS pipelines.

Actions

Applies if your site uses Hugo 0.161.x or later and runs PostCSS, Babel, Tailwind, or similar Node tools during the Hugo build.

• Upgrade Node to the active LTS release. For Docsy 0.16.0, use Node LTS 24.
• Build locally and check for Node permission errors.
• If your CI keeps node_modules outside the project tree (for example, Netlify’s shared cache) and the build fails with ERR_ACCESS_DENIED, upgrade to Hugo 0.163.2.
• If your project uses Tailwind, install Tailwind as an npm package. Hugo no longer supports the standalone Tailwind binary in this path.

Content and resource security (0.161.x-0.163.x)

Hugo tightened several security boundaries in this range:

• security.http.urls defaults became more restrictive, and resources.GetRemote re-checks redirects.
• text/html content files are denied by default unless allowed through security.allowContent.
• Symlinked entries are rejected or ignored by more template/resource functions, including resources.Get and, in 0.163.1, os.ReadDir, os.ReadFile, os.Stat, and os.FileExists.

Docsy’s own workspace and smoke-test install shapes were validated across these changes, but site-specific mounts, symlinks, and remote resource fetches are always project-specific.

Actions

Applies if your site uses remote resources, hand-authored .html content files, or symlinked content/assets.

• Build locally with your target Hugo version and review security-related errors or warnings.
• If you intentionally publish .html content files, configure security.allowContent explicitly.
• If templates call resources.GetRemote, review security.http.urls and test redirecting URLs.
• If your content or assets are symlinked into the project, test those pages and consider replacing symlinks with Hugo mounts or real files if Hugo blocks them.
• If templates use templates.Defer inside partialCached, move that deferred work outside the cached partial; Hugo now reports this invalid combination instead of silently doing the wrong thing.

Imaging deprecations and URL churn (0.163.x)

Hugo 0.163.0 deprecated global imaging quality settings in favor of per-format settings. It also introduced AVIF-related imaging configuration and changed internal resized-image cache keys.

Docsy’s website configuration was streamlined as part of the upgrade: settings that matched Hugo defaults were removed, and resampleFilter: CatmullRom was kept because it materially affects photo downscaling quality.

Actions

Applies if your site config uses global imaging.quality or imaging.compression.

• Replace global settings with per-format settings, or remove them if they match Hugo defaults.
• Keep resampleFilter: CatmullRom if your site relies on Docsy-style sharp photographic downscaling.

For example:

imaging:
  resampleFilter: CatmullRom

Image URL churn

Applies if your site commits generated output, compares public builds, or uses a CDN that caches generated image resources aggressively.

Hugo 0.161.x-0.163.x can change resized-image filenames that contain _hu_<HASH> even when the source image and visual output are unchanged. Treat this as expected cache-key churn. It can create noisy diffs and cache misses, but it is not usually a content regression.

Other deprecations and notable changes

Template and config deprecations

Review these if your site has custom templates, external content converters, or JavaScript tooling config:

• .IsNode is deprecated; use .IsBranch.
• jsconfig baseUrl support was removed.
• If you read Git metadata from module-mounted pages, verify .Page.GitInfo output. Hugo 0.162.0 fixed GitInfo handling for modules whose go.mod lives in a repository subdirectory.
• If you use --renderSegments, prefer Hugo 0.163.1 for its segment-merge fix.
• If your site renders Pandoc or reStructuredText content through external converters, Hugo 0.163.2 now fails the build when the converter binary is missing (matching AsciiDoc) instead of silently publishing raw content; ensure the converter is installed wherever you build.

Security fixes

This range includes multiple security-related updates, including Go html/template fixes and stricter URL/content handling. This is a strong reason to prefer 0.163.2 over stopping at the minimum 0.158.0.

New features worth knowing about

• css.Build and later hugo:vars support may be useful for site-specific CSS pipelines, but Docsy has not moved its Sass/PostCSS pipeline to css.Build.
• AVIF image processing was added and then tuned in the 0.162.x-0.163.x range.
• strings.ReplacePairs is available for template authors on Hugo 0.158.0 or later.

Upgrade to Hugo 0.163.2

After addressing applicable breaking changes and deprecations, upgrade to Hugo 0.163.2.

If you use the hugo-extended npm package:

npm install hugo-extended@0.163.2 --save-dev

If you use hvm:

hvm use 0.163.2

Recommended minimum Hugo version

Docsy 0.16.0 requires Hugo 0.158.0 or later:

module:
  hugoVersion:
    min: 0.158.0

For local builds, deployments, and new upgrades, we recommend Hugo 0.163.2.

Release 0.16.0 report and upgrade guide

Release summary

• Theme folder move: the canonical theme files moved under theme/, separating the consumer-facing theme tree from repository and website tooling (#2641, #2645).
• Hugo support:
  • The theme minimum moved from Hugo 0.146.0 to 0.158.0.
  • The Docsy project build was upgraded to Hugo 0.163.2.
  • Theme templates and docs moved off deprecated Hugo language APIs (#2647, #2648, #2649).
• Favicons:
  • The theme no longer ships default favicon artwork.
  • The default partial discovers and links common favicon filenames from a site’s static/ directory.
  • A gen-favicons helper can generate raster icons from a source SVG (#2357, #2595, #2653, #2654, #2656).
• Shared chrome build mode (experimental): a new opt-in td.chrome = shared mode that emits the repeated chrome (navbar, footer, left-nav) once per language and restores it in the browser, so one build serves both readers and link checkers; the default full mode is unchanged (#2659, #2660, #2662).
• Other notable changes:
  • Theme runtime dependencies now live in theme/package.json.
  • The repository uses npm workspaces for docsy.dev and theme.
  • Test coverage now includes Hugo deprecation checks and small fixture-site regression tests.

Ready to Upgrade?

• Review BREAKING changes:
  • Theme folder move
  • Minimum Hugo version
  • Default favicons removed
  • Bootstrap and Font Awesome via npm
• Review the companion Hugo 0.158+ upgrade guide if your site is not already building cleanly with Hugo 0.163.2.
• Optionally skim:
  • New favicon discovery behavior
  • Experimental shared chrome build mode
  • Repository packaging cleanup
  • PostCSS is opt-in for non-RTL sites
  • Other notable changes
• Jump to Upgrade to 0.16.0 once you are ready.

/ Theme folder move

Docsy’s canonical theme tree has moved from the repository root to theme/. This is the main structural change in 0.16.0.

For most sites, the upgrade is intentionally small: update the place where Hugo looks for the theme. The exact edit depends on how your site installs Docsy.

This change lets the project keep the installable theme surface lean while moving repository-only tooling, website tooling, tests, and release automation out of the theme’s way. It also makes theme/package.json the owner of theme runtime dependencies such as Bootstrap and Font Awesome.

Actions

Replace VERSION with the Docsy version you want to install, for example v0.16.0.

Hugo module sites

Applies if your site imports Docsy as a Hugo module.

Change the module import path from github.com/google/docsy to github.com/google/docsy/theme:

# OLD
module:
  imports:
    - path: github.com/google/docsy

# NEW
module:
  imports:
    - path: github.com/google/docsy/theme

Then update the module:

hugo mod get github.com/google/docsy/theme@VERSION
hugo mod tidy

Users still request @v0.16.0 in the command above. The release process creates the matching nested Hugo module tag, theme/v0.16.0, at the same commit as the repository release tag.

GitHub NPM package sites

Applies if your site installs Docsy from GitHub with npm and uses themesDir: node_modules.

Change the theme path:

# OLD
theme: docsy
themesDir: node_modules

# NEW
theme: docsy/theme
themesDir: node_modules

The install command shape is otherwise unchanged:

npm install --save-dev google/docsy#semver:VERSION --omit=peer

Git clone or Git submodule sites

Applies if your site keeps Docsy under themes/docsy/ as a clone or Git submodule.

Change the theme path:

# OLD
theme: docsy

# NEW
theme: docsy/theme

For a fresh clone install, use this setup shape:

cd themes
git clone -b VERSION https://github.com/google/docsy
(cd docsy && npm run postinstall)
cd ..

For a Git submodule install, keep your existing submodule update workflow, then run the same docsy postinstall step after updating the submodule.

Hugo 0.158+ support

Docsy 0.16.0 raises the theme’s minimum supported Hugo version to 0.158.0. Theme templates now use Hugo’s newer language APIs, introduced in 0.158.0, so sites building with Hugo 0.157.x or earlier must upgrade Hugo before or while upgrading Docsy (#2581, #2593).

The Docsy project build is validated with Hugo 0.163.2. We recommend moving directly to 0.163.2 unless your project has a reason to pin a lower version. For the detailed Hugo changes between 0.158.0 and 0.163.2, see the companion Hugo 0.158+ upgrade guide.

Actions

Applies to all projects upgrading to Docsy 0.16.0.

• Upgrade to Hugo 0.158.0 or later. Prefer Hugo 0.163.2.
• If your site declares module.hugoVersion.min, set it to at least 0.158.0.
• If your multilingual site config still uses Hugo’s older language keys, consider updating them:
  • languageName -> label
  • languageDirection -> direction
• If your site overrides Docsy templates or language-related partials, check for deprecated Hugo language API names such as .Language.Lang, .LanguageName, and .LanguageDirection.

The old language config keys still work in site configuration, but updating them keeps builds quiet as Hugo moves deprecations from info messages toward warnings and, later, errors. For current Docsy examples, see Multi-language support.

/ Bootstrap and Font Awesome via npm

Applies to Hugo-module installs. If your site uses Docsy as a Hugo module, the upgrade needs one new step (see Actions). Sites that install Docsy as an npm package or via clone or submodule are unaffected — they continue to get Bootstrap and Font Awesome through Docsy’s postinstall.

Docsy now sources Bootstrap and Font Awesome from npm rather than importing each project’s GitHub repository as a Hugo module. Those imports were a workaround, since neither project publishes a Go module. Hugo’s first-class npm-module support makes them unnecessary: theme/package.json declares Bootstrap and Font Awesome, and hugo mod npm pack delivers them to your project. This also retires the theme’s generated Go-module requires, a module-sync script, and a Bootstrap rfs vendor workaround (#2668).

Actions

Applies if your site imports Docsy as a Hugo module.

After updating the Docsy module, consolidate and install the theme’s npm dependencies:

hugo mod npm pack
npm install

Re-run hugo mod npm pack whenever you update Docsy; Hugo warns when the dependency set drifts.

PostCSS is opt-in for non-RTL sites

Docsy now runs postCSS only for sites with RTL languages (which need it for rtlcss) or that provide a project-root postcss.config.{js,mjs,cjs}. Other sites no longer need a PostCSS toolchain at all and can drop autoprefixer, postcss, and postcss-cli from their dependencies.

Docsy’s CSS targets the Browserslist defaults browsers. To keep Autoprefixer (or other PostCSS plugins) for a non-RTL site, add a project-root postcss.config.js and install your own PostCSS dependencies.

/ Favicons

Docsy no longer ships default favicon artwork. Sites now own their favicon files, which avoids accidentally publishing Docsy-branded icons on downstream projects.

To keep the common case simple, Docsy’s default favicon partial now discovers and links conventionally named files from your site’s static/ directory. A site that provides files such as static/favicon.ico, static/favicon.svg, and static/apple-touch-icon.png gets the matching <link> elements without overriding a partial.

For the full filename list and helper command reference, see Add your favicons.

Actions

Applies if your site relied on Docsy’s bundled default favicon files.

• Add your own favicon files under static/.
• Build your site and inspect the generated page <head> to confirm the icon links you expect are present.

Applies if your site overrides layouts/_partials/favicons.html.

• Keep your override if you need custom link tags, non-default filenames, a web app manifest, or additional platform icons.
• Otherwise, consider deleting the override and using the default discovery behavior documented in Add your favicons.

If you have a source SVG and ImageMagick installed, you can generate the common raster files with the new helper:

npx gen-favicons static/favicon.svg static/

Shared chrome build mode

Docsy 0.16.0 adds an experimental shared chrome build mode. With td.chrome = shared, Docsy renders the repeated page chrome – the top navbar, the footer, and the left sidebar navigation – on a single donor page per language, then restores it in the browser on every other page using the theme’s chrome-nav.js runtime. The default mode, td.chrome = full, renders complete chrome on every page exactly as before.

The motivation is the contributor and CI experience, not a change to your published site. Because the chrome’s many repeated links appear on one page instead of on every page, a shared build is dramatically cheaper to link-check, output-diff, and preview – the outer loop of working on a site – while readers still get the full page once JavaScript runs. The default full mode stays the default, and a normal production build is unchanged.

The existing large-site navigation optimization is intact and generalized, not lost. A full build on a site above sidebar_cache_limit still renders the left-nav once as a shared cached menu; 0.16.0 only moved that activation from per-page inline jQuery into the shipped chrome-nav.js. As a result, chrome-nav.js now loads on every page regardless of build mode – worth a note for JS-audit-conscious sites, and harmless for everyone else.

Think of shared mode as a small, experimental first step toward a more component-oriented Docsy, where shared page regions are authored and shipped once. For configuration, the kept-or-restored contract, and current limitations, see Chrome build modes. This feature is experimental and may change.

Actions

Applies if you want faster link-checking, output diffing, or previews – especially for a large or multilingual site.

• No action is required. full is the default and existing sites are unaffected.
• To try it, build with td.chrome set to shared (for example, HUGO_PARAMS_TD_CHROME=shared) for non-production builds such as link-checking or CI, and keep full for published output.
• Because shared mode is experimental, don’t rely on it for production HTML yet. See Chrome build modes.

Other notable changes

Repository and package layout

The Docsy repository now has a clearer package boundary:

• theme/ contains the theme files that consuming sites need.
• theme/package.json owns Bootstrap and Font Awesome runtime dependencies.
• docsy.dev/ owns the website build and site-specific tooling.
• The repository root owns workspace orchestration, release tooling, and tests.

This is mostly a maintainer-facing cleanup. The user-facing effect is the theme path change covered in Theme folder move.

Build and test guards

Docsy’s own test suite now includes guards for Hugo deprecation output and small fixture-site regression tests. These checks helped validate the Hugo 0.158.0 to 0.163.2 upgrade range and the new theme folder install matrix.

Upgrade to 0.16.0

Some upgrade steps are the same for each Docsy release, such as updating your Docsy package or Hugo module. Those steps are described in Upgrade to Docsy 0.12.0: follow them, using version 0.16.0 where the guide refers to 0.12.0. For this release, use:¹

• Docsy: 0.15.0 -> 0.16.0
• Hugo: 0.157.0 -> 0.163.2 (theme minimum: 0.158.0)
• Node: LTS 24 (unchanged)

What’s next?

The 0.16.0 release closes the main user-facing pieces of the theme-folder move. Follow-up repository cleanup and future packaging work continue under Finalize monorepo setup - 26Q2 (#2617).

References

About this release:

• Changelog entry for 0.16.0
• Release page for 0.16.0
• Release 0.16.0 preparation issue (#2615)
• Git history since 0.15.0

Release 0.15.0 report and upgrade guide

Release summary

• Agent support (experimental):
  • Generated llms.txt
  • Markdown page output
  • “View Markdown” page-meta link
• Doc-rooted sites (experimental): documented pattern and example variant for sites whose docs section is published at the site root
• Version menu entries: headings, separators, per-entry page-link behavior, and kind-specific styling
• Content, shortcodes, and internationalization:
  • Community and footer links
  • card shortcode rendering
  • Internationalization additions and updates

Ready to Upgrade?

• Review BREAKING changes:
  • Community and footer links
  • Version menu entries
  • Card shortcode rendering (low risk)
• Optionally skim:
  • New features (look for the green checkmark icon)
  • Cleanup / improvement opportunities (look for this icon)
  • Other notable changes
• Jump to Upgrade to 0.15.0 once you are ready

Agent support

Release 0.15.0 includes the phase 1 implementation of agent support, which provides opt-in features that help AI agents and automated tools discover and use your site content, including:

• llms.txt
• Markdown alternate outputs for home, section, and page content.
• A View Markdown page-meta link when a Markdown page alternative exists.

To learn more, including configuration details on how to enable agent support for your site, see Agent support. This feature is experimental.

To track the phased evolution of the agent-support feature, see Improve support for AI-agent doc consumption #2614.

Doc-rooted sites

Docsy provides new and improved support for doc-rooted sites. That is, sites whose docs section is published at the site root instead of under /docs/. This is useful when your site is primarily documentation and you want shorter URLs such as /get-started/ instead of /docs/get-started/.

Doc-rooted sites also support having non-docs sections at the site root, such as a blog or community page. For details, see Doc-rooted sites and visit the Doc-rooted example variant of this site. This feature is experimental.

Actions

Applies if your project uses an older docs-only configuration based on front matter cascade or type changes.

• Remove the older docs-only cascade configuration.
• Use Hugo permalinks configuration for the docs section as described in Doc-rooted sites.
• Check for path conflicts with hugo --printPathWarnings. With the proper setup, there should be no conflicts.

/ Version menu entries

Docsy’s navbar version menu now has richer entry handling so your site can use text headings, separators, per-entry page-link behavior, and kind-specific styling for menu entries. For configuration details, see Adding a version drop-down menu.

Existing simple version and url entries continue to work. The change is potentially breaking if your project customizes the version menu partial, CSS, or mobile navbar layout: the menu uses updated markup and classes, and it is no longer hidden on smaller viewports.

Actions

Applies if your project configures params.versions and customizes the version menu or navbar.

• Review custom CSS that targets the version menu dropdown.
• If you maintain a local layouts/_partials/navbar-version-selector.html or layouts/_partials/navbar.html override, diff it against the v0.15.0 navbar partials.
• Recheck the navbar on both desktop and mobile viewports.

For configuration and styling details, see the Version menu and Adding a version drop-down menu.

/ Community and footer links

New behavior and fixes:

• Footer links support rel attributes, see Adding a community page (#2576).
• Community and footer links now open in a new browser target only for external links, fixing #2133 (#2576).
• Site-local community and footer links resolve under any permalinks scheme (#2580).

Breaking change:

• For multilingual sites, link paths are now interpreted as site-relative paths. (#2580).

Actions

Applies if your multilingual site configures community or footer links with site-local paths.

• Review params.links.user and params.links.developer path values. For each, determine whether the path should target the default language or be site (locale) relative.

• If the path should be site-relative, leave the path as is.

• If the path should target the default-language site (paths that live under the default language prefix), add that prefix – for example /en/community/ instead of /community/.

  Note

  If your default language is served at the site root, for example with defaultContentLanguageInSubdir: false or a site-matrix/default-language fallback setup, a path like /community/ may already point at the default language. Only add the language prefix when the prefixed URL exists and is the canonical target you want.

• Recheck generated community and footer links in each language to ensure they target the desired site.

/ Card shortcode rendering

While the card shortcode has always supported Markdown content in its arguments, the arguments are now rendered in the context of the page that includes the card. This means that argument values (Markdown) resolve in the page context, which allows:

• Relative link paths can be used in card argument Markdown
• Markdown render hooks will fire in the page context

Relative link paths are an important capability to have in multilingual sites. Executing render hooks in a page context allows for more flexible hook behavior.

For example, the following card footer argument illustrates the use of a relative path to an image page-bundle resource:

{{< card
  header="**Imagine**" ...
  footer="![John's signature](card-pane/john-lennon-signature.png)"
>}}
...
{{< /card >}}

For the complete example, see card shortcode.

Actions

Applies if your project uses the card.html shortcode or maintains a custom override.

• Ensure that cards still render as expected.
• Update your site’s card override if you want to take advantage of new capabilities.

Other notable changes

Internationalization

Summary of changes:

• Translation files for the following locales have been created or updated:
  • Azerbaijan: new (#2082, #2604).
  • Romanian: new (#2583, #2603).
  • German: added alert-label translations (#2591).
• Baseline translations for the new “View Markdown” label (#2602).

Upgrade to 0.15.0

Upgrading with AI? 0.15.0 ships an experimental machine-readable upgrade manifest with upgrade-detection rules, applies-if gates, sanity checks, and per-item references. Use this release report and the manifest as context for your AI assistant.

Some upgrade steps are the same for each Docsy release (for example, updating your Docsy NPM package or Hugo module). Those steps are described in Upgrade to Docsy 0.12.0: follow them, using version 0.15.0 where the guide refers to 0.12.0. For this release, use:¹

• Docsy: 0.14.3 → 0.15.0
• Hugo: 0.155.3 → 0.157.0
• Node: LTS 24 (unchanged)

What’s next?

For general work items tentatively planned for the next release, see Release 0.16.0 preparation (#2615).

References

About this release:

• Changelog entry for 0.15.0
• Release page for 0.15.0
• Release 0.15.0 preparation issue (#2501)

Release 0.14.0 report and upgrade guide

Release summary

• Styles and customization:
  • Navbar improvements, including configurable light/dark theme and adjustable height
  • Heading aliases and in-page targets
  • Reorganized internal SCSS files

    ⚠️ If you customize Swagger UI, this impacts you!

• Content, shortcodes, and internationalization:
  • New Markdown alert syntax
  • blocks/cover shortcode changes
  • New shortcode for Netlify build info
  • Internationalization updates
• Hugo 0.155.0 or later required; discussion of breaking changes and new features such as sites.matrix
• Public vs internal features: added definitions for customization surface, private/internal, and support limits

Ready to upgrade?

• Review BREAKING changes:
  • Styles and customization
  • Heading aliases and in-page targets
  • blocks/cover shortcode content processing
  • Hugo 0.155.0 requirement and 0.153+ breaking changes
  • (style-only) Docsy 0.14.2 code-style update for light/dark mode
• Optionally skim:
  • New features (look for the green checkmark icon)
  • Cleanup / improvement opportunities (look for this icon)
  • Other notable changes
• Jump to Upgrade to 0.14.0 once you are ready

Markdown alert syntax

Docsy 0.14.0 adds support for Hugo’s Markdown alert syntax that looks like this:

> [!NOTE] :star: Markdown alert syntax
>
> This syntax is more author, tooling, and AI friendly.

Which renders as:

We still support the alert shortcode, but recommend the Markdown alert syntax for new content. For the new alert syntax and customization, see Alerts.

Actions (optional)

Applies if your project uses the alert shortcode. Consider migrating to Markdown alerts for consistency and better authoring/tooling support:

• Use Markdown alert syntax for new content.
• Where the output is equivalent, replace existing alert shortcodes with the Markdown syntax.
• Keep alert shortcodes when you rely on shortcode-specific behavior.

Styles and customization

This section covers breaking changes (marked ⚠️) and new features for the navbar, internal SCSS file reorganization and its impact on Swagger UI customization.

Navbar style improvements

Highlights:

• Light or dark navbar theme is now configurable site-wide or per page, defaulting to your site’s theme otherwise.
• Navbar height is now adjustable via a single SCSS variable!
• New variables and classes make it easier to customize the navbar look.
• Navbar over cover images now has improved styles and translucency behavior.
• No more accidental SCSS file overrides! Internal SCSS files now live under the private td/ subdirectory.

Before 0.14.0, the navbar always used a dark theme and primary-colored background. The navbar’s light/dark color theme is now configurable site-wide and per page, defaulting to your site’s theme. The default navbar style matches your base site’s style for a consistent look and feel.¹

Navbar height and styling are tunable via (EXPERIMENTAL):

• SCSS variables:

  • $td-navbar-min-height
  • $td-navbar__main-min-height-mobile
• CSS variables

  • --td-navbar-bg-color
  • --td-navbar-backdrop-filter
  • --td-navbar-border-bottom
  • --bs-bg-opacity, used with --td-navbar-bg-color for background opacity
  • --bs-link-underline-opacity, nav link underline

Learn more about the default Navbar appearance and Customizing the navbar.

Actions: required and optional

You may need to update your project in the following areas:

• / Navbar light/dark color theme: the always-dark navbar was an early Docsy constraint and isn’t a fit for all sites. You can now choose the theme that best matches your project’s overall design.

  • If your design does not require a dark navbar, you may be able to drop any overrides you added just to force that theme.
  • If your design does require a dark navbar, set params.ui.navbar_theme to dark to restore the previous behavior (details).

• Navbar over cover: applies if your project targets navbar cover translucency classes.

  • Review and simplify your styles (navbar cover-image translucency).
  • Replace .navbar-bg-on-scroll and .navbar-bg-onscroll--fade with .td-navbar-transparent (used alongside .td-navbar-cover).

• Height and variables: applies if you customize navbar height or styling. Review and simplify your customizations using the new variables and styles — see Customizing the navbar.

• Navbar partial overrides: applies if your project overrides the navbar partial. Review _nav.html for changes.

  Summary of edits to layouts/_partials/navbar.html

  Before	After
  Cover translucency
  - `	- `
  Light/dark theme
  - `data-bs-theme="dark"` always set on `	- `data-bs-theme="dark"` only when `params.ui.navbar_theme` is `"dark"` - Otherwise follows site theme

  For details, see the previous bullets of this Action required section.

Heading aliases and in-page targets

Heading aliases are a useful convention for keeping old fragment links working. In 0.14.0, scrolling behavior is fixed (purely in CSS using scroll-padding-top), so heading alias targets and in-page targets now scroll to the right place. For details, see the Heading aliases and in-page targets and PR #2505 changes.

Actions: required and optional

• Applies if your site uses td-offset-anchor; for example, if you override blocks/lead.html, blocks/section.html, or layouts/community/list.html.

  Rename td-offset-anchor to td-anchor-no-extra-offset. See Implementation notes.

• Scrolling behavior: applies if you want to ensure proper scrolling behavior for your project’s existing heading aliases and in-page targets.

  • Update heading aliases and in-page targets to be of the form <a id="..."></a>, if not already.
  • In particular, replace non-anchor targets such as <span> elements with <a id="..."></a> for more reliable scrolling.
  • Replace legacy targets like <a name="..."> with id-based targets.

Improved separation of project and internal SCSS files

Docsy 0.14.0 moves all its internal SCSS files from assets/scss/ into the assets/scss/td/ subdirectory. This change clearly distinguishes project style files from internal theme files and helps projects avoid accidental overrides of Docsy’s internal SCSS files. For details on how to customize Docsy’s look and feel for your project, see Project styles that covers:

• The project style files that are supported for project-specific SCSS customization
• Advanced style customization for projects that occasionally need to deviate substantially from Docsy’s base styles

Actions: required and optional

Applies if your project has any of the files in assets/scss/ listed next, because you are overriding Docsy’s internal SCSS files.²

assets/scss/
├── _alerts.scss
├── _blog.scss
├── _boxes.scss
├── _breadcrumb.scss
├── _code.scss
├── _colors.scss
├── _content.scss
├── _drawio.scss
├── _main-container.scss
├── _nav.scss
├── _navbar-mobile-scroll.scss
├── _pageinfo.scss
├── _search.scss
├── _sidebar-toc.scss
├── _sidebar-tree.scss
├── _swagger.scss
├── _table.scss
├── _taxonomy.scss
├── _variables_forward.scss
├── _variables.scss
├── blocks/_blocks.scss
├── blocks/_cover.scss
├── section-index.scss
├── shortcodes.scss
├── shortcodes/cards-pane.scss
├── shortcodes/tabbed-pane.scss
├── support/_bootstrap_vers_test.scss
├── support/_mixins.scss
├── support/_rtl.scss
└── support/_utilities.scss

To continue using your customizations from, for example, assets/scss/_table.scss, add the following import to your _styles_project.scss file:

@import 'table';

Alternatively, you can copy the styles directly into _styles_project.scss.

Swagger UI style customization

Applies if your project customizes Swagger UI styles.

Before 0.14.0, the User Guide incorrectly recommended overriding _swagger.scss to customize Swagger UI styles. Internal SCSS files are not meant to be overridden; the guide has been corrected. Because the override was documented, moving the file is considered a breaking change and so we are calling it out as such.

If your project has Swagger UI style customizations, follow the steps outlined in the previous section’s Action required.

blocks/cover shortcode changes

Two changes to blocks/cover, the first of which is a breaking change:

1. The shortcode now uses .Inner content directly, relying on Hugo’s native Markdown content processing instead of file extension testing (#939, #2480).

2. New td-below-navbar helper class lets you position the cover below the fixed navbar on desktop, instead of behind it.

Actions: required and optional

• Applies if you use blocks/cover in .html content files with Markdown in the body.

  Use Hugo’s shortcode Markdown call syntax: {{% %}}. Otherwise, Markdown content might not render correctly.

• Recommended for most projects.³ If you want to position your blocks/cover below the navbar (instead of behind it), add the td-below-navbar helper class to your blocks/cover call. For example: height="auto td-below-navbar". See Below-navbar height adjustment.

Hugo requirement and breaking changes

Docsy 0.14.0 officially supports Hugo 0.155.0 or later, up from 0.152.2 in Docsy 0.13.0. Hugo 0.153+ introduce breaking changes that may affect your site, as well as major new features such as the multidimensional content model provided through sites.matrix.

For all the details, see our companion post on Hugo 0.152.0-0.155.x upgrade guide. For a comprehensive list of issues and considerations when moving to Hugo 0.153+, see Hugo 0.153+ breaking changes & issues (#2431).

/ Patch update 0.14.2

Docsy 0.14.2 adds the following changes:

• For sites using td/code-dark, default code styles changed from tango/onedark to friendly/native (#2548).
• Console block selection and copy-code now include commands only, not output (#2548). For details, see Selecting console block content.
• Search form now includes a name attribute for better semantics and autofill behavior (#2549).

Actions: required and optional

• Applies if you use td/code-dark and you want to revert to the tango/onedark styles. Follow the steps in Light/dark code styles and more.
• Verify that copy-code behavior in console examples (commands only) matches your expectations. To use the old behavior, see Selecting console block content.

Other notable Docsy changes

Internationalization

Summary of changes:

• Theme i18n converted from TOML to YAML; redundant other form entries removed in favor of default singular/plural syntax (#2447).
• New locale: Hebrew.
• Alert type labels added to multiple locales (#2390).

Action (optional): applies if your project has i18n files. You have an opportunity to clean up and reduce technical debt:

• Remove redundant entries from your files where Docsy’s additions or updates already cover them.
• Simplify your i18n files by dropping redundant other form entries (whether you convert to YAML or not).

Style improvements and fixes

Docsy 0.14.0 includes the following style improvements and fixes:

• Navbar color contrast fixes (#2413, #2477)
• <details> margin fixes
• TOC h1 entries made slightly bolder so they are more visually distinct
• Google-search modal support for dark mode (#2524)
• RTL: code blocks and foldable-nav icons (#2533)

Experimental extra styles:

• CTA buttons group style: use the td-cta-buttons class
• Navbar link decoration for active and hover states
• Nested-list margin fix for the last child
• No-left-sidebar layout: use the td-no-left-sidebar class
• Navbar helper class td-navbar-links-all-active for homepage

For details, see Extra styles.

Shortcodes

• New experimental td/site-build-info/netlify shortcode for Netlify build info. See an example.

Clarified public vs internal theme features

Docsy 0.14.0 adds definitions to clarify Docsy’s public customization surface, internal/private features, and support limits, so expectations are clear about what’s supported and what changes require action:

• Public customization surface
• Private/internal features
• Experimental features
• Breaking change
• Official support limits

Upgrade to 0.14.0

Upgrade steps

Some upgrade steps are the same for each Docsy release (for example, updating your Docsy NPM package or Hugo module). Those steps are described in Upgrade to Docsy 0.12.0: follow them, using version 0.14.3 where the guide refers to 0.12.0. For this release, use:⁴

• Docsy: 0.13.0 → 0.14.3
• Hugo: 0.152.2 → 0.155.0 or later, see Hugo 0.152.0-0.155.x upgrade guide
• Node: LTS 24 (unchanged)

What’s next?

For general work items tentatively planned for the next release, see Release 0.15.0 preparation (#2501).

Goals and feedback

Our goal is for this post to help Docsy project maintainers upgrade to 0.14.0, with a focus on actionable items. Let us know how we can improve it by opening an issue or starting a discussion.

References

About this release:

• Changelog entries from 0.14.0 to 0.14.3
• Release pages for 0.14.3, 0.14.2, 0.14.1, and 0.14.0
• Release 0.14.0 preparation issue (#2404)

Other references:

• Companion Hugo 0.152.0-0.155.x upgrade guide
• 0.13.0 upgrade guide
• Hugo release notes

Hugo 0.152.0-0.155.x upgrade guide

This post summarizes the breaking and notable changes in Hugo 0.152.0 to 0.155.3. It is a companion post to the Docsy 0.14.0 and 0.13.0 release and upgrade guides.

Upgrade summary

This guide highlights breaking changes in Hugo 0.152.0–0.155.x and the actions you may need to take.

• Review BREAKING changes:
  • YAML yes/no tokens are strings
  • Build order changes for multidimensional sites
• Review deprecations (non-breaking, but recommended):
  • lang mount option deprecated
  • includeFiles/excludeFiles deprecated
• Optionally skim:
  • Known issues and fixes
  • Notable changes
• Jump to Upgrade to Hugo 0.155.x once you’re ready

YAML yes/no tokens are strings (0.152.0)

Release 0.152.0 (2025-10-21) upgrades to a more modern YAML library, which introduces a breaking change to the way that YAML interprets certain tokens across configuration files and page front matter.

Previously, the bare (unquoted) tokens yes, no, on, off, etc. were treated as boolean values. They are now treated as strings. For the complete list of tokens, see 0.152.0 release notes.

Actions: required and optional

• Applies if your project has YAML with unquoted yes, no, on, off, and similar tokens. Update them to true or false.

  Search for these unquoted key or value tokens:

  • yes, Yes, YES, y, Y, on, On, ON: change to true
  • no, No, NO, n, N, off, Off, OFF: change to false

  Example:

  # OLD (now broken in 0.152.0+)
  enabled: yes
  disabled: no
  
  # NEW (correct)
  enabled: true
  disabled: false
  

• Applies if your project has custom page Feedback configuration. You can now drop quotes around keys (or values) containing the tokens yes, no, etc..

  # OLD
  params:
    ui:
      feedback:
        enable: true
        'yes': Glad to hear it! ...
        'no': Sorry to hear that. ...
  
  # NEW
  params:
    ui:
      feedback:
        enable: true
        yes: Glad to hear it! ...
        no: Sorry to hear that. ...
  

Multidimensional content model (0.153.0)

Release 0.153.0 (2025-12-19) introduces, among other things, a powerful new multidimensional content model (over versions and roles in addition to the previously supported languages dimension) through the new sites.matrix configuration option.

Breaking and deprecation changes related to multidimensional sites are summarized next.

Build order for multidimensional sites

Hugo now builds sites based on sorted dimensions (by weight, then name) instead of starting with the default content language. This also affects .Site.Sites sort order.

Actions: required and optional

Applies if your project relies on a specific site build order or indexing into .Site.Sites by position, for example by accessing .Site.Sites by index. Update your logic to select the default site explicitly.

How you fix your code will depend on how you access the sites. For example, if your code contains index site.Sites 0, then replace it with site.Sites.Default. For more concrete examples, see open-telemetry/opentelemetry.io#8850.

Deprecations

lang mount deprecation

Actions (recommended)

Applies if you use lang on mounts. Switch to sites.matrix to avoid deprecation warnings.

For example:

# OLD (deprecated)
- source: content/fr
  target: content
  lang: fr

# NEW
- source: content/fr
  target: content
  sites:
    matrix:
      languages: ['fr']

For a concrete example, see open-telemetry/opentelemetry.io#9070.

includeFiles/excludeFiles deprecation

The includeFiles/excludeFiles file mount options are deprecated in favor of the files filter with negation support.

Actions (recommended)

Applies if you use includeFiles or excludeFiles in mounts. Switch to files to avoid deprecation warnings.

For example:

# OLD (deprecated)
- source: content
  target: content
  excludeFiles: ['drafts/**']

# NEW
- source: content
  target: content
  files: ['! drafts/**']

For a concrete example, see open-telemetry/opentelemetry.io#9070.

Known issues and fixes

Alias handling in 0.153.x

Notable changes

Notable changes that are non-breaking include:

0.155.0

• Version and dimension range queries are now supported in the sites matrix (e.g., >= v1.0.0).
• Page aliases now work properly in multidimensional sites.
• XMP and IPTC image metadata support was added.

0.154.0–0.154.5

• Partial decorators introduced (inner keyword) for powerful template composition.
• New Page.OutputFormats.Canonical method (0.154.4).
• New reflect.* functions, such as reflect.IsPage.
• Critical fixes for alias handling and site redirects in multidimensional/multihost setups.

0.153.0

• WebP encoding/decoding now uses libwebp via WASM. The extended edition is no longer required for WebP.
• Animated WebP support, including conversion to/from animated GIFs.
• GoogleAnalytics.RespectDoNotTrack default changed to true.
• Duplicate content path warnings were removed (less noisy, but may hide issues).
• macOS distributions are now distributed solely as signed and notarized .pkg installers, .tar.gz is no longer supported. See the notes below.

Upgrade to Hugo 0.155.x

After addressing all breaking changes and deprecations, upgrade to the latest release of Hugo 0.155.x. If you use the hugo-extended NPM package, you can upgrade to the latest version by running:

npm install hugo-extended@latest

If you use hvm to manage your Hugo version, you can upgrade to the latest version by running:

hvm use latest

Recommended minimum Hugo version

For projects using the new sites matrix features who also want the latest fixes and updated support for aliases in the context of multidimensional sites, we recommend using Hugo 0.158.0 or later:

module:
  hugoVersion:
    min: '0.158.0'

Release 0.13.0 report and upgrade guide

Release summary

Docsy 0.13.0 comes with the following notable features and fixes:

• Navigation and UX improvements including the most upvoted enhancement request of 2025: Active TOC entry tracking (#349, #2289)
• Alert shortcode rewrite for better Markdown support
• Accessibility enhancements for better color contrast and dark mode support

Ready to upgrade?

• Review BREAKING changes:
  • Alert shortcode body content processing changes
  • Language menu visibility changes
• Optionally skim:
  • New features
  • Other notable changes
• Jump to Upgrade to 0.13.0 once you are ready.

Navigation and UX improvements

Active TOC entry tracking

Docsy 0.13.0 introduces active table of contents (TOC) entry tracking, the most upvoted enhancement request of 2025. This feature highlights the TOC entry corresponding to the page’s section that is currently in view. The feature is implemented using (a patched version of) Bootstrap’s ScrollSpy. The new default TOC labels “On this page” and “Top of page” are localizable. For details, see Active TOC entry tracking with ScrollSpy.

Section sidebar root

Docsy 0.13.0 introduces the sidebar_root_for configuration option, which allows you to scope sidebar navigation to specific sections. This is particularly useful for large sites where you want different navigation trees for different sections, and docs-only sites that also have non-docs sections.

To enable this feature, add sidebar_root_for to your page front matter. Supported parameter values are children and self. For details and examples, see the Section sidebar root documentation; for implementation details, see #2328 and PR #2364.

Language menu visibility

Prior to Docsy 0.13.0, the language selector menu was shown for multilingual sites in both the navbar and the sidebar, depending on the viewport width according to the following table:

The change in visibility was triggered by the Bootstrap lg breakpoint (the point where layouts switch between wide and narrow).

The new visibility under 0.13.0 is as follows for all viewport widths:

This is a BREAKING UX change. You can recover legacy behavior as follows:

• Navbar: add the following SCSS (or equivalent) to your project’s styles to restore the previous d-none d-lg-block behavior:

  .td-navbar__lang-menu {
    @extend .d-none;
    @extend .d-lg-block;
  }
  

• Sidebar: set the optional parameter .ui.sidebar_lang_menu to true in your site configuration.

To learn more about the language menu, see Adding a language menu. For implementation details, see #2035, #2001, and PR #2303.

Mobile navbar scroll indicators

The navbar now shows left/right scroll indicators when the navigation menu overflows (mainly for narrow viewports), making it easier for users to discover additional navigation items (#2406).

Alert shortcode improvements

As of Docsy 0.13.0, alert shortcode content is processed differently when called as Markdown ({{% alert %}}): the inner Markdown is now passed through to the page’s Markdown renderer and processed along with the rest of the page content. Previously, the shortcode used Hugo’s markdownify function internally.

This change means that your alerts can now:

• Contain calls to other shortcodes, that is, nested shortcode calls
• Contain and share link definitions from or with other parts of the page
• Be used in lists and other indented contexts
• Include headings that appear in the page TOC (for docs pages)

For details and examples, including important formatting requirements, see alert. For implementation details, see PR #941.

Action required: Applies if you use the alert in .html content files with Markdown in the body.

Use Hugo’s shortcode Markdown call syntax: {{% %}}. Otherwise, Markdown content might not render correctly.

Sanity check: sample the rendering of pages that contain alert shortcodes, whether in Markdown or HTML content files. Ensure that the alert renders as expected.

Accessibility improvements

• Color contrast has been improved throughout the theme, and Docsy now falls back to Bootstrap defaults for typography and color. This ensures better accessibility compliance out of the box. For details, see #2285 and Site colors.

• Color contrast improvements for dark mode:

  • TOC entry color contrast has been fixed when user preferences differ from system settings (#2379).

  • Early experimental support for customizable color-contrast adjustments for projects using Bootstrap’s theme variables (#2384). For details, see How to pick colors with good color-contrast. EXPERIMENTAL

• Dark mode:

  • Flash Of Unstyled Content (FOUC) has been fixed (#2332).
  • Google search results page now supports dark-mode (#2387). EXPERIMENTAL
  Dark mode quick reference

  To opt into all dark mode features (including experimental ones), add the following imports to your _styles_project.scss. For details, see Light/dark color modes.

  // Dark mode enhancements
  @import 'td/color-adjustments-dark';
  @import 'td/code-dark';
  @import 'td/gcs-search-dark';
  

Other notable changes

• Better NPM support: Projects using Docsy via NPM will no longer face optional and peer dependency issues (#2115).

• Translations (i18n): Occitan locale has been added (#2173), and Simplified Chinese (#2313) and Ukrainian (#2331) translation files have been refreshed.

• New _param shortcode: A new experimental shortcode for parameter substitution in templates, useful for dynamic content generation. See PR #2371 for details.

• Mathematical and chemical formulae: Docsy now uses Hugo’s embedded KaTeX engine for build-time rendering. The mhchem extension is now built-in. For details, see LaTeX support with KaTeX (#2276, #2394, #2395).

  The KaTeX engine auto-activates when formulae are encountered; no configuration needed, so projects can remove the following obsolete site configuration: params.katex.*. Subfields include enable, html_dom_element, options, and mhchem.

Upgrade to 0.13.0

Prerequisites

We recommend that you Upgrade to Docsy 0.12.0 first because it contains significant breaking changes.

Upgrade procedure and AI help

Have you used AI to help you upgrade Docsy? It can be a big help!

The 0.12.0 upgrade guide was written with both human project maintainers and AI assistants in mind. In fact, I’ve successfully used it to upgrade projects like The Update Framework website. That is, using only the upgrade guide as input, an AI assistant created TUF PR #126 fully autonomously. All I had to do was review it.

Some upgrade steps are the same for each Docsy release (for example, updating your Docsy NPM package or Hugo module). Those steps are described in Upgrade to Docsy 0.12.0: follow them, using version 0.13.0 where the guide refers to 0.12.0. For this release, use:

• Docsy: 0.12.0 → 0.13.0
  Includes Bootstrap: 5.3.6 → 5.3.8
• Hugo: 0.147.5 → 0.152.2 ²

  See Hugo 0.152.0 breaking changes.

• Node: LTS 22 → LTS 24 ²

After upgrading, review the breaking changes and test your site thoroughly. For a testing checklist, see the Upgrade to Docsy 0.12.0 guide.

What’s next?

There are exciting enhancements planned for 2026³!

For general work items tentatively planned for the next release, or to track our progress, see Release 0.14.0 preparation (#2404). Some of the currently most upvoted enhancement requests include:

• Repository / page-meta link fixes and improvements (#1841), particularly for GitLab support (#375)
• Drop jQuery (#1436)

References

About this release:

• 0.13.0 changelog entry
• 0.13.0 release page
• Release 0.13.0 preparation issue (#2266)

Other references:

• 0.12.0 upgrade guide
• For Hugo upgrade considerations when moving from 0.147.5 to 0.152.2, see:
  • Hugo 0.152.0 breaking changes, our companion post
  • The official Hugo release notes

Upgrade to Docsy 0.12.0 from 0.11.0

Since we didn’t publish a release announcement for 0.12.0, I’m using this opportunity to walk through the upgrade process from 0.11.0 to 0.12.0.

TL;DR: The main breaking changes in Docsy 0.12.0 stem from Hugo’s new template system, which causes layouts subfolder and filename changes.

In this post you’ll walk through the upgrade process for:

• Docsy: 0.11.0 → 0.12.0
• Hugo: 0.136.2 → 0.147.5 ¹
• Node: LTS 20 → LTS 22 ¹

Procedure overview

1. Update Docsy and Hugo versions
2. Move custom layout files and folders
3. Check for additional required changes
4. Test your site

Update Docsy, Hugo, and more

1. Update Node.js

Docsy officially supports the active LTS release of Node.js. As of 0.12.0, this is Node.js 22. To update your Node.js version, we recommend using nvm:

nvm install --lts

This command will both install and select the latest LTS version for your shell session (Linux and macOS).

2. Update Docsy

• If using NPM:

  npm install --save-dev google/docsy#semver:0.12.0
  

• If using Hugo modules:

  hugo mod get -u github.com/google/docsy@v0.12.0
  

• If using Git submodule:

  cd themes/docsy
  git fetch --tags
  git checkout v0.12.0
  cd ../..
  git add themes/docsy
  

3. Update Hugo

Update Hugo to 0.147.5, even if you are targeting a higher version of Hugo. We recommend that you update to a higher version in a separate step, after the Docsy upgrade.

How you do this depends on how your project manages its Hugo dependency. For projects using hugo-extended, update the NPM package version. Update the NPM lockfile or any cache keys to force a CI/CD cache refresh. For example:

npm install --save-exact -D hugo-extended@0.147.5

4. Install dependencies

If using Git submodule, install Docsy dependencies:

npm install
(cd themes/docsy && npm install)

Move custom layout files and folders

In line with Hugo’s new template system, Docsy v0.12.0 reorganized its layouts directory². While not mandatory, we recommend updating your project’s layout files and folders to match Docsy’s new Hugo-conformant layout structure as follows:

• Move _markup one level up:

  layouts/_default/_markup/  → layouts/_markup/
  

• Add underscore prefixes to subfolders:

  layouts/partials/     → layouts/_partials/
  layouts/shortcodes/   → layouts/_shortcodes/
  

• Relocate and rename taxonomy files (if applicable):

  layouts/_default/taxonomy.html → layouts/term.html
  layouts/_default/terms.html    → layouts/taxonomy.html
  

The following commands can help you move your custom layout files and folders :

1. Move your custom layout files and folders:

   # If you have custom partials
   git mv layouts/partials/* layouts/_partials/
   
   # If you have custom shortcodes
   git mv layouts/shortcodes/* layouts/_shortcodes/
   
   # If you have custom markup render hooks
   git mv layouts/_default/_markup/* layouts/_markup/
   
   # If you have custom taxonomy layouts
   git mv layouts/_default/taxonomy.html layouts/term.html
   git mv layouts/_default/terms.html layouts/taxonomy.html
   
   # Clean up empty directories
   rmdir layouts/partials layouts/shortcodes layouts/_default/_markup layouts/_default
   

2. Update Docsy template references:

   If you have layouts/_markup/render-heading.html that references Docsy’s heading template:

   - {{ template "_default/_markup/td-render-heading.html" . -}}
   + {{ partial "td/render-heading.html" . -}}
   

   Note: The td prefix moved from filename to the directory path.

Check for additional required changes

1. Image fingerprints

Skip this step if your project’s CSS/SCSS does not use blocks/cover hero/background images.

Hugo generates new image fingerprints. Projects that refer to hero/background image paths in their CSS/SCSS will need to update references to the new image fingerprints. This includes projects with strict Content Security Policy (CSP) configurations, for example.

1. Build your site: npm run build
2. Check public or resources/_gen/images/ for image file names with new fingerprints
3. Update references in your stylesheets

2. Taxonomy files

If your project overrides taxonomy layouts, note that in addition to moving the files, you need to:

• Swap the layout files
• Rename the terms file to be singular: terms.html → term.html

For CLI commands, see the Move layout files step.

3. Internal layout content.html file rename

If your project overrides Docsy layouts/**/content.html files:

• Prefix your file names with _td-: content.html → _td-content.html

These are the affected files:

layouts/_td-content-after-header.html
layouts/_td-content.html
layouts/blog/_td-content.html

Test your site

Build your site to check for errors, especially template-not-found errors and missing layout files:

npm run build

We recommend doing this for both development and production builds.

Then serve your site to verify that it renders as expected. For example:

npm run serve

Testing checklist

Use this checklist to verify that your upgrade succeeded:

• Build succeeds without errors, warnings, or deprecation notices; CSS and other asset files are rendered
• Key pages (e.g. home, a doc page, a blog post) load with no 404s or broken layout
• Nav links resolve; breadcrumbs show current path; current section is highlighted
• On mobile or tablet: navigation is usable and key pages have no horizontal scroll
• External links show expected styling (e.g. icon)
• Heading self-links work and are styled correctly
• Dark mode toggle works (if enabled)
• Custom shortcodes render correctly (if used)
• Search returns expected results (if used)
• Print preview looks correct (if used)

References

For the full release notes, see:

• Docsy v0.12.0 changelog
• Hugo release notes from 0.136.2 (or your starting Hugo version) to 0.147.5.

Other references:

• Hugo 0.146.0 template system
• 0.11.0 release highlights
• 0.11.0 changelog
• Docsy issue #2243, Adapt to new template system in Hugo v0.146.0.
• 0.13.0 release report and upgrade guide — for upgrading from 0.12.0 to 0.13.0

Docsy 2024 Review: Adoptions and Enhancements

As we reflect on 2024, it’s exciting to see steady progress toward the goals outlined in our 2024 priorities. This year, we focused on enhancing stability, improving internationalization, and delivering long-anticipated features like dark mode and continuous integration (CI) testing.

Docsy’s use increased by 57% in 2024, from 1.4K to 2.2K projects! ¹

Let’s dive into the development highlights from 2024 and take a peek at what lies ahead.

Release highlights

We published three releases this year, each focusing on stability while introducing at least one major feature enhancement. Highlights include:

• 0.9.0 added long-awaited:
  • CI testing via GitHub Actions to ensure quality and reliability across Linux and Windows.
  • Footer customization — Docsy’s longest-standing issue (#2)! — as well as improved repository links, and enhanced accessibility and look-and-feel.
• 0.10.0:
  • Enabled color themes and dark mode via Bootstrap 5.3 upgrade, marking the completion of the Bootstrap 5 migration started in 2021. Also made adjustments to shortcodes and styles for dark-mode compatibility.
  • Addressed breaking changes resulting from the major core upgrade to Hugo 0.123.0.
• 0.11.0:
  • Enhanced internationalization by reintroducing Right-To-Left (RTL) language support using Bootstrap’s RTL capabilities.

Major feature enhancements

In addition to CI testing, a key development feature contributing to Docsy’s stability, here are the major user-facing enhancements introduced in 2024.

Dark mode support

Dark mode support was the most upvoted Docsy enhancement prior to its debut in v0.10.0. Powered by Bootstrap 5.3 color themes, this Docsy feature includes a built-in light/dark mode menu selector for easy implementation.

We plan on enabling dark mode in the Docsy example, for even easier adoption. Dark mode has already been adopted in notable projects like OpenTelemetry (opentelemetry.io#4023).

Right-To-Left (RTL) language support

RTL language support (#1933), reintroduced through Bootstrap’s use of the mature and well-vetted RTLCSS framework, replaced Docsy’s deprecated custom RTL solution from 2023.

This enhancement meets longstanding multilingual documentation needs. Notably, RTL support has been requested by major Docsy-based sites, including the two 2024 top-velocity projects of the CNCF:

• Kubernetes: right-to-left language support #22730
  • Localize website into Arabic (ar) #22726
  • Localize website into Persian (fa) #22727
• OpenTelemetry:
  • Add Persian version of website pages #4990

Adoptions and the Docsy Starter

One of the most exciting developments in 2024 has been Docsy’s growing adoption. GitHub analytics show a 57% increase in usage, reaching 2.2K projects as of this writing.

Adoption among CNCF projects has also grown since our 2023 report. This year, Linux Foundation mentees Sandra Dindi and Dariksha Ansari used the CNCF Docsy starter to migrate the following sites to Docsy:

• The Update Framework (theupdateframework.io#105)
• in-toto (in-toto.io#76)

Additionally, the Kubernetes website is undergoing a significant Docsy upgrade from v0.2, to align with the latest version and reduce technical debt:

• Align with upstream Docsy kubernetes.io#41171
• Update Docsy step by step to the latest Docsy kubernetes.io#44002

The upgrade is progressing well, as shown in the ongoing efforts documented in the 0.3.x upgrade and 0.5.x upgrade.

What’s ahead?

Looking ahead, we’re excited to continue supporting the Docsy upgrade and adoption efforts by projects such as gRPC (grpc.io#1389) and Jaeger (jaegertracing#746).

For features tentatively planned for the first release of 2025, see Release 0.12.0 preparation #2108. The most upvoted enhancement requests are currently: ²

• Navigation indication on the right TOC #349
• Repository / page-meta link fixes and improvements #1841, particularly for GitLab
• Drop jQuery #1436

Thank you to all contributors and users who made 2024 a meaningful year for Docsy. Wishing you a fantastic end to 2024 and a great start to 2025! Let’s continue creating exceptional documentation together.

Docsy 0.10.0 release report

The big news with Docsy 0.10.0 is color themes and dark mode!

Hugo: breaking changes and deprecation notices

In this release, Docsy’s Hugo dependency is upgraded to 0.125.4 from 0.122.0. An important thing to note here is that Hugo 0.123.0 was a significant upgrade that included some breaking changes. Before upgrading to this Docsy version, review Hugo’s deprecation notices and breaking changes since 0.122.0.

A number of updates to this release were to address Hugo’s deprecation notices. For the complete list, search for 0.10.0 release changes with “deprecat” in the title.

Color themes and dark-mode support

The main feature of this release is the Upgrade to Bootstrap 5.3 (#1528) from 5.2. This minor Bootstrap release introduces support color modes, also called color themes.

As a validation of this upgrade, Docsy has been enhanced to support dark mode, the most upvoted Docsy enhancement request (#331) prior to this release.

To learn how to enable a light/dark mode dropdown menu for your project, see Light/dark mode menu. We have enabled this menu for the Docsy User Guide, so if you’re reading this post online, give dark mode a try!

Release details

For the complete list of changes in this release, including updates to FontAwesome, Mermaid, Algolia, and KaTex, see the 0.10.0 release entry and issue Release 0.10.0 preparation (#1759).

What’s next?

Which Docsy improvements are on the horizon? For work items tentatively planned for the next release, see Release 0.11.0 preparation (#1944).

Docsy 0.9.0 release report

Docsy 0.9.0 is a sizable¹ release (containing 65+ PRs) that has some breaking and notable changes worth calling out, namely those related to:

• Footer improvements
• Repository links and other page info
• Look and feel
• Continuous integration testing

Thank you to all contributors!

Footer improvements

For a list of all footer improvements and fixes included in this release, see #1818. We mention a few in this section. More footer improvements, for even easier customization, are planned for the next major release (#1852).

Footer layout changes

In support of easier footer customization, the footer layout has been factored into parts: left, right, and center (#1500), with copyright as a subpart of center (#1817). Each part has its own class, such as td-footer__left, for easy style customization. Note that the class td-footer__copyright-etc has been renamed to td-footer__center.

Footer copyright date-range and more

Oh my! We’ve closed issue #2!

This release has resolved the longest standing and first ever issue created in Docsy!

• The footer should allow a more flexible copyright statement (#2) by @sarahmaddox

The footer copyright now supports a date-range and the site-copyright as a fallback:

• The Hugo config option params.copyright, previously a string, can now also be a map with the following optional fields: authors, from_year, to_year. When unset, to_year defaults to the year that the site built. The default authors is “<Site.Title> Authors” and this field is rendered as markdown.
• If params.copyright is unset, then the site copyright configuration option will be used and rendered as markdown “as is” — with no date(s) added.

Footer streamlined

• The About-page footer link is now hidden by default. To enable this link, set .params.ui.footer_about_enable to true in your project’s configuration file. Parameter .params.ui.footer_about_disable is deprecated.
• The All-rights-reserved text is hidden by default. To make it visible, add the following to your _styles_project.scss project style file (optionally with a !important modifier — not shown):

  .td-footer__all_rights_reserved {
    display: inline;
  }
  

Repository links and other page info

Repository links

Getting repository links right has eluded Docsy maintainers and contributors since 2019 (#138). The challenge is ensuring that repository links work for all Docsy-based projects regardless of their setup for single- or multi-language support, or whether they have a homepage.

At last, steering committee member Lisa’s determination has paid off. Half-jokingly, Lisa commented: All we needed was several years and a few Hugo improvements. That is, it wasn’t until Hugo 0.112.0, released in May 2023, that the necessary functions became available. For details, see:

• Fix links for single language sites (#1744)
• Hugo v0.112.0 - New template functions, by @jmooring

We’re convinced that Lisa’s fix has squashed repo-link bugs for good!

As mentioned in the CHANGELOG, this is a breaking change for sites that use mounts and that have pages configured with path_base_for_github_subdir.

As can be seen from Repository / page-meta link fixes and improvements (#1841), several issues remain, but resolving #1744 establishes the necessary foundation for future work. The issues listed in #1841 will be addressed in a future release through further layout refactoring and extension.

Last-modified page info

You can configure your site to display page-source last-modified metadata at the bottom of documentation and blog pages. For details, see the newly added User Guide section Last-modified page metadata.

Look and feel

Heading self links

Docsy has switched to build-time generation of heading self links using Hugo’s render-heading.html hook, replacing client-side rendering via assets/js/anchor.js (dropped in #1460). Projects must now explicitly enable the feature. For details, see Heading self links.

Formerly an embedded SVG, the default self-link symbol is now CSS-defined to be #, a common choice for websites. Projects can customize the appearance of the heading self link through the .td-heading-self-link class.

Heading self links are now:

• Always visible on mobile and touch devices
• For other devices and screens, the link is invisible until the user hovers over the heading (as before)

Accessibility: Links are underlined

Docsy now follows recommended accessibility practice: page-body links are underlined by default. For details, see #1814 and #1815.

Bye bye ellipsis

The blocks/feature shortcode no longer includes ellipsis ("…") after the “Read more” link text. Projects wanting to recover the ellipsis can add it to the "ui_read_more" language parameter for your site’s languages (#1820).

Continuous integration testing

To ensure the quality and stability of Docsy, this release introduces a highly anticipated developer feature: continuous integration (CI) testing support through GitHub Actions.

Each PR and main-branch commit triggers (workflows):

• Cross-platform tests on Linux and Windows.
• Build tests to ensure that Docsy and its User Guide build successfully and pass checks, such as link validation.
• Smoke tests that build a Docsy site from scratch. These tests validate Docsy’s use as both a Hugo module and an NPM module.

While Windows support is maintained on a best-effort basis due to limited access to Windows environments, running cross-platform tests helps identify potential build issues sooner.

This initiative is an important step forward in ensuring the reliability of the theme. We plan to expand test coverage (#726) in the future.

References and future releases

For the complete list of changes in this release, see the 0.9.0 release entry and issue Release 0.9.0 preparation (#1759).

Which Docsy improvements are on the horizon? For work items tentatively planed for the next release, see Release 0.10.0 preparation (#1812).

Feature and fix candidates for 0.10.0 and beyond currently include more Bootstrap work, in preparation for the reintroduction of RTL support — specifically:

• BSv5.2 upgrade followup
• Upgrade to Bootstrap 5.3 (#1528)
• [BSv5] Reintroduce RTL support using RTLCSS bootstrap
• Support adding theme colors

Docsy priorities for 2024

TL;DR 1.4K projects use Docsy! The top user-project focused priorities for 2024 are: improving Docsy’s stability, usability & customizability, and cohesiveness while performing feature consolidation.

Docsy is a popular theme

The Hugo-Docsy tool combo is powerful and effective, as I’ve blogged about elsewhere. It’s maybe no surprise then, to see Docsy used by 1.4K projects¹. Why is Docsy popular? I can’t say for sure, but I use and recommend Docsy because it has the core features — necessary for publishing non-trivial tech-doc sites — that projects seem to want and need, including support for versioning, multiple languages, auto-generated site navigation, and more. It’s quick to set up, and it allows projects to focus on delivering site content rather than writing site template code.

User-project focused and long-term vision

Steering committee members, including myself, are actively supporting several projects at the CNCF and Google that rely on Docsy. Both as users and contributors to Docsy, we share a vested interest in ensuring Docsy’s long-term health. Our envisioned priorities for Docsy are:

1. Stability of Docsy’s core through bug fixes and necessary upgrades — the migration from the end-of-life Bootstrap 4 to version 5 is one example of such an effort.
2. Reducing technical debt.
3. Improving usability, customizability, and maintainability by, in particular, working to more clearly separate and document “API surfaces” — or configuration / customization surfaces.
4. Feature consolidation, which I will explain next.

Google open sourced Docsy a little over five years ago, and thanks to community contributions, it has grown in stability and its feature set. During that time, Docsy also accumulated considerable technical debt, and it now suffers (IMHO) from a mild case of software bloat/feature creep. So, in addition to investing in Docsy’s long-term stability and maintainability, we need to reaffirm Docsy’s core features and deprioritize the rest² — lest we suffer a fate similar to projects like cross-env. Consider Docsy on a feature diet.

Before tackling 2024 objectives, we plan on setting up a test infrastructure with (a growing) suite of tests to help us ensure Docsy’s integrity as it evolves.

Conclusion

This is a tall order for 2024 and beyond, but I believe that slow and steady wins the day.

We’re eager to hear from you, the Docsy community! Share your thoughts on our focus areas and how we can enhance Docsy. Take a look at our issue triage into quarterly milestones for a rough idea of what is targeted for upcoming releases. Vote for or comment on issues that are important to you, and we’ll do our best to respond and adjust release targets within the boundaries of our set priorities. Better yet, volunteer to work on the current quarter’s tasks. As we start the new year, we’ll be especially interested in getting help with testing and feature consolidation.

Upgrade to Docsy 0.7 & Bootstrap 5

Last June, Docsy celebrated a significant milestone with the release of version 0.7.0. This major upgrade was the result of six months of meticulous work (#470) focused on the migration to Bootstrap 5.2. For highlights and the rationale behind that journey, see Migrating to Bootstrap 5.2.

This blog post is intended to help those who are upgrading to Docsy 0.7 and Bootstrap 5, based on my Docsy 0.7 upgrade experiences, specifically related to Bootstrap. The post starts with general guidance for Docsy-based projects wishing to upgrade. Every project’s migration experience will be unique, but hopefully this post, and the two included case studies, will make your upgrade process easier and faster.

If you’re here, you probably want to upgrade your Docsy-based project—so, let’s jump in!

Upgrading your project

As was mentioned in the first post, each project uses its own specific set of Bootstrap and Docsy features, so in all likelihood, your upgrade journey will be unique. This section offers some general guidance.

Upgrade Docsy

If you haven’t already, upgrade your project all the way up to Docsy 0.6 first. Each release of Docsy can bring its own set of upgrade challenges that will vary in size and effort depending on your project and the features it uses, as well as how long it’s been since your version of Docsy has been upgraded. You’ll want to get all pre-0.7 upgrade issues out of the way so that you can focus on Bootstrap 5 issues. Once you are done, upgrade to the latest Docsy 0.7.x release.

Address Bootstrap changes

I recommend that you first walk through the Bootstrap 5.2 migration page to get an appreciation of the scope of the changes made to Bootstrap 5 relative to 4. Identify the breaking changes to those Bootstrap features used by your project, and address each individually. I mention a few breaking changes next and close the section with a comment about what to do about the rest.

Some Bootstrap changes will break your website’s layout or functionality in obvious ways. This is the case for the rename of utility classes, like ml-1 and pr-2. Using regular-expression based search-and-replace over your project’s custom layouts or doc-page inline HTML is a good way to tackle this. I’ve used regex like these:

• Margin and padding: \b([mp])[lr](-([0-5]|auto))\b
• Left/right classes: \b((float|border|rounded|text)-)(left|right)\b

If your project uses Bootstrap JavaScript plugins such as dropdowns, popovers, and tooltips, these will stop working until you adjust data attribute names, which are now “namespaced” using the data-bs prefix. For example, use data-bs-toggle instead of data-toggle.

Other Bootstrap breaking changes will require more work to address, such as the following that were mentioned in the TL;DR of the first post:

• Mixin media-breakpoint-down() argument shift
• Grid .row and .col style changes
• Import ordering of Bootstrap Sass files: functions first

The Docsy blog layout used the .media class, which was dropped from Bootstrap 5. This, and the .row and .col style changes, required a couple of iterated changes to the blog layouts, such as PR #1566. If your project customizes blog layouts, then you’ll want to walk through the updates carefully. Otherwise, your project will get these updates automatically, without any further required changes.

Should you encounter a Bootstrap-5 breaking change affecting your project that hasn’t been mentioned above, you might find the opening comment of Docsy issue #470 · Upgrade to Bootstrap 5.2 useful: it lists 50 tasks, each addressing a distinct migration problem, accompanied by notes or cross-referenced PRs that illustrate how each problem was resolved.

Address Docsy-specific changes

It is worth mentioning in passing some of the main Docsy 0.7 changes that aren’t related to Bootstrap, such as:

• Default and accepted values of the blocks/section’s type argument have changed (#1472)
• Pre-Hugo-0.54.x behavior of {{% %}} is no longer supported (#939)
• Hugo release 0.110.0 or later is required

For the complete list of changes, see the CHANGELOG at 0.7.0.

Case studies

Our two case study projects to illustrate the Docsy upgrade process are the OpenTelemetry project and the Docsy example template repository.

opentelemetry.io

Several CNCF projects use the Docsy theme, including opentelemetry.io, which I used as a Docsy pre-release test site. As suggested earlier, I first upgraded Docsy from 0.4 to 0.6 (opentelemetry.io issue #2419).

The upgrade to Docsy 0.7 went fairly smoothly. In addition to addressing the “obvious changes” related to utility class renames and data-attribute namespacing, the OTel website required these project-specific changes:

• Breaking changes to forms required a significant rework of the Registry form
• While the OTel website has no blog layout overrides, it made use of the .media class (which was dropped) for registry entries. Flex styles were used instead.

That’s it! To see how both of the above were resolved, see OTel PR #2490.

Docsy-example

The docsy-example repository is a GitHub template that we suggest as a possible starting point for users looking to adopt Docsy for a new website. The example site features multi-language support, which had an impact on the required upgrades.

The example-site upgrade was even simpler than for the OTel website. The key changes (PR #221) were mainly confined to the landing page of each natural language:

• Utility-class renames, such as .ml-* and .mr-* to .ms-* and .me-*
• blocks/section changes (PR #1472):
  • Language landing pages had to be renamed from .html to .md in support of using blocks shortcodes to render markdown content
  • Switched to type="row" for blocks/section elements that are rows (also from PR #220)

That was it.

What next?

If your project doesn’t override any Docsy layouts, then your upgrade experience should be relatively straightforward. Reviewing layout file changes, on the other hand, always warrants special attention.

With the tips shared here, I hope that your journey to Docsy 0.7 will be more streamlined. Consider sharing your experiences by adding a comment to the discussion of 0.7.0 or any later 0.7.x release. Wishing you a successful upgrade journey!

A special thanks to Erin McKean for detailed and valuable feedback on this post, and to all who contributed to the 0.7.x releases of Docsy and the Docsy example!

Migrating to Bootstrap 5.2

Docsy, and Docsy-based project websites (including those at the CNCF), have been happily using the Bootstrap CSS framework from Docsy’s inception. In January of this year, Bootstrap 4 (the version used by Docsy for the past few years) reached its end of life. While we, the Docsy steering committee, have been eager to benefit from the Bootstrap 5 improvements, we were concerned about the magnitude of the migration effort, as well as the impact on downstream projects. Because of this, the migration was delayed for as long as possible. In December of 2022, when Bootstrap 4 stopped receiving critical upgrades, we declared Docsy to be in a feature freeze, and focused our maintenance efforts on the Bootstrap 5 migration.

This post is about Docsy’s migration journey to Bootstrap 5.2¹: it highlights the most notable steps, with a special attention given to the most surprising aspects of the migration. Our hope is that this post will be useful to others upgrading to Bootstrap 5, in particular, for downstream Docsy projects — though we plan a separate post specifically for downstream projects.

TL;DR

Eager to dive into the Bootstrap migration of your project? Besides carefully stepping through the Bootstrap migration page, watch out for the following:

• The media-breakpoint-down() mixin’s breakpoint argument needs to be shifted.
• Grid .row and .col style changes are breaking.
• Import ordering of Bootstrap Sass files: import functions first.

For details, read on.

Technical details

If you are well accustomed to upgrading Docsy (and its dependencies) by reading changelogs and systematically stepping through commits, then this section provides a summary of some notable changes. In it, I describe technical aspects of the migration that surprised me, either because they required particular care in fixing, were undocumented, and/or insufficiently explained in the Bootstrap migration page.

Mixin media-breakpoint-down() argument shift

The breakpoint argument to the media-breakpoint-down() mixin needs to be bumped up to the next higher breakpoint. Thankfully, a similar change isn’t required of media-breakpoint-up(). This change will be required of Docsy-based projects. If you forget to make this non-obviously breaking layout change, your project’s responsive layouts will likely start misbehaving in apparently strange ways.

For details and an example, see:

• Sass section of the migration page
• [BSv5] Adjust media-breakpoint-down() argument · Docsy PR #1367

Grid .row and .col style changes are breaking

The main issue addressed in this section is not, at the time of writing, documented in the Bootstrap 5 migration page.

There seems to be an assumption, in Bootstrap 5, that the immediate child of a .row should be a .col. I don’t know how strict an assumption this is. While I have searched for an explicit statement of this assumption in the Bootstrap documentation, I haven’t found one yet — if you are aware of such a statement, let us know!

This assumption wasn’t apparent nor was it enforced in Bootstrap 4, consequently, some of Docsy’s layouts failed to respect it. In most cases, fixing violations consisted of simply wrapping a .row’s child element in a .col, but the Docsy footer required a couple of iterations to get right.

My first footer adjustment reset flex-shrink to its default value (PR #1373), but that turned out to be unnecessary once I better understood how to appropriately handle row margins (PR #1523) — rows have negative margins, as I recently learned, which is something to keep in mind.

The following Bootstrap 5 .col style changes influenced Docsy-specific style updates and might impact Docsy-based projects as well:

• position is reverted to its default value of static from relative
• flex-shrink default value of 1 is overridden and set to 0

References:

• [BSv5] Row/col formatting breaks Docsy components #1466, in particular
  • [BSv5] Footer fixes: reset flex-shrink, and more · Docsy PR #1373
  • [BSv5] Footer: drop flex-shrink tweak + other adjustments · Docsy PR #1523
• Why are all col classes ‘position: relative’? · Bootstrap v4 issue #25254
• Why flex-shrink 0 for all columns? · Bootstrap discussion #37951

Import ordering of Bootstrap Sass files: functions first

Projects can import Bootstrap Sass sources all in one go (using bootstrap.scss), or selectively import any one of the 40+ Bootstrap parts, layouts, and components that they need. Regardless of the import strategy chosen, due to a Sass map initialization limitation, Bootstrap-client projects need to perform (emphasis mine):

… variable customizations … after @import "functions", but before @import "variables" and the rest of [the Bootstrap] import stack.

For details, see New _maps.scss from the migration page, and Importing from Bootstrap’s Sass customization documentation.

Having to maintain a custom list of a few dozen imports (even if it’s relatively stable) feels like a maintenance overhead that we should avoid if we can, so in Docsy’s main.scss, we @import “functions” before Docsy- and project-specific variable overrides, and then we import the full Bootstrap suite of SCSS. This results in _functions.scss being imported twice, but according to the Sass @import documentation:

If the same stylesheet is imported more than once, it will be evaluated again each time. If it just defines functions and mixins, this usually isn’t a big deal, but if it contains style rules they’ll be compiled to CSS more than once.

The _functions.scss file only contains function definitions, so we should be ok. This seems like a small cost to pay in contrast to the alternative strategy of inlining the 40+ imports from bootstrap.scss.

References:

• [BSv5] Fix SCSS functions import issue … · Docsy PR #1388
• New _maps.scss from the migration page
• Importing from Bootstrap’s Sass customization documentation

Systematic and stepwise migration

If you’ve glanced at the Bootstrap 5 migration page, you will see that there are a lot of changes to address while migrating. To ensure that we didn’t miss any, we systematically walked through the migration guide, and tracked the status of each change through Docsy issue #470. Each relevant migration page section is represented in the issue’s opening comment: we either noted that a migration-page section is irrelevant for Docsy, or added the section to the tracking issue, and list the PRs containing corresponding Docsy-specific changes. If you’re curious to see how that worked out, see Upgrade to Bootstrap 5.2 · Docsy issue #470.

First Bootstrap 5 release of Docsy

A first Bootstrap 5 release of Docsy is planned for the start of June, since most aspects of the migration have been completed. Some updates have been postponed, most notably support for right-to-left (RTL) text. For the complete list of followup items, see BSv5.2 upgrade followup · Docsy issue #1510.

As was mentioned earlier, this first release will be in support of Bootstrap 5.2. We plan a separate migration effort to bring Docsy up to Bootstrap 5.3, in particular to benefit from new color modes. You can track our progress through Docsy issue #1528.

Migrating Docsy-based projects

This section contains some preliminary and general guidance for downstream projects. We are planning a separate post to cover more migration details.

Bootstrap migration-page walkthrough

Each project uses its own specific set of Bootstrap features, so walking through the Bootstrap 5.2 migration page will be advisable for most projects. Of course, one strategy is just to upgrade and see what breaks or no longer works, but only doing that without a more systematic follow-up would be ill-advised for all but the most trivial projects—consider the challenge in detecting and recovering from a missed change to a ​​media-breakpoint-down() argument, as discussed earlier.

Docsy-specific changes

During the migration effort we seized the opportunity to do some long overdue Docsy house cleaning. For details concerning both breaking and non-breaking Docsy-specific changes, consult the changelog. In particular, one non-breaking but important change to be aware of is: [BSv5] Docsy variables cleanup … PR #1462.

Give it a try!

To get a first and quick impression of the impact of the upgrade on your project, it can be informative to simply upgrade Docsy and see what breaks. This is what the Docsy team did with Bootstrap 5. Only one change actually broke the build of the Docsy User Guide: the rename of the color-yiq() function.

After such a smoke test, we recommend systematically walking through the Bootstrap migration page as described above, and the Docsy changelog. I used this approach for opentelemetry.io, which was the first Docsy-based project to be upgraded with a pre-release of Bootstrap-5-based Docsy. The upgrade went quite smoothly. The main pain point of the OTel website was upgrading to Bootstrap 5 forms; an aspect of the migration that didn’t apply to Docsy since Docsy uses only the most trivial of forms.

We’ll have more to share about the OTel migration effort as well as general project-specific migration advice in a followup blog post. In the meantime, I hope that you have found parts of this technical article helpful for your own migration efforts.

CNCF project websites eager to migrate can send questions to the CNCF #techdocs Slack channel. CNCF and other Docsy-based projects can also start a discussion in the Docsy repository. Happy migrating!

A big thanks to the Docsy Steering Committee and other reviewers who offered feedback on earlier drafts of this post, as well as to all those who contributed to the migration effort.

A version of this article originally appeared as the CNCF blog post Migrating Docsy to Bootstrap 5.

Hello Docsy!

Hello

It may seem strange to see a “Hello” post from a project that’s several years old, but as Docsy matures as a community-driven project, we thought it was time to (re)introduce ourselves and talk about what’s new with your favorite (we hope) Hugo documentation theme!

Discuss amongst yourselves

Our Discussions are really hopping lately! Don’t miss our notice of the upcoming deprecation of the Font-Awesome and Bootstrap git submodules or our announcement of our new governance model!

Milestones, releases, and roadmaps

We are planning our first official release of Docsy soon—check out the milestones for 0.2.0. Got a suggestion for the roadmap? Open an issue.

Coming soon: project metrics

Starting next month, we’ll publish project metrics here on this blog.

Introducing the PSC

Docsy now has a Project Steering Committee! The PSC members are @chalin, @LisaFC, @geriom, and @emckean. If you’re interested in serving on the PSC, open an issue and nominate yourself!

Contribute to the blog!

Also coming soon: contribution guidelines. Got an idea for a blog post? Open an issue!