Update Docsy

These pages apply to Docsy v0.16.0 and compatible versions, and target release refers to the Docsy version that you are updating your site to. For what changed in a given release, and any release-specific upgrade actions, see the upgrade blog posts.

Before you begin

• Backup or safeguard your project’s current state: for example, work from a Git branch, merging only after checking your site, or back up your project files first. Rolling back is then a simple restore.
• Updating from Docsy 0.15 or earlier? First apply the theme-path config changes, and only those, from the 0.16.0 post’s theme folder actions; this page’s steps cover the rest.

Order of steps

Perform the update steps in the order given by this page:

1. Node.js and Hugo, when your target release calls for it
2. The theme, by install mode
3. Review your theme overrides
4. Check your site

Update Node.js

Applies if your target release names a newer Node.js version than your project uses; its upgrade blog post says so. With nvm, install and select that version, for example:

nvm install NODE_VERSION

Replace NODE_VERSION with the version that the upgrade post names.

Update Hugo

Applies if your target release raises the minimum or recommended Hugo version; its upgrade blog post says so. For projects using the hugo-extended NPM package, update the package version, for example:

npm install --save-exact --save-dev hugo-extended@HUGO_VERSION

Replace HUGO_VERSION with the version that the upgrade post names.

After updating, also refresh any CI/CD cache keys so that builds don’t reuse a cached Hugo.

Update the theme

How you update the theme depends on the way that Docsy is installed in your project. Follow the page matching your install mode:

• Hugo module
• NPM package
• Git submodule or clone

The remaining update steps apply to all install modes.

Review your theme overrides

If your project overrides theme files, then after updating, diff each override against its new theme counterpart and port upstream changes as needed. Look for overrides in your project’s:

• assets/
• i18n/
• layouts/, the most common location
• static/

Docsy’s project style files (_variables_project.scss and friends) also work this way, but the theme’s copies are placeholders that are intentionally empty: there’s nothing to diff, so they don’t need this review.

Check your site

After updating, build or serve your site and check for errors and warnings. We recommend building both development and production versions of your site, since they can differ in their configuration, minification, etc.

Use this checklist as a guide to verify that your update succeeded:

• Build completes without warnings or deprecation notices
• Key pages load and have proper layout, for example the site home, a doc page, and a blog post. On each page:
  • Browser console shows no errors
  • Nav links resolve; breadcrumbs show current path; current section is highlighted
  • External links show expected styling (for example, icon)
  • Heading self-links work and are styled correctly
  • On mobile or tablet: navigation is usable and there is no horizontal scroll
• Dark mode toggle works, if enabled
• Custom shortcodes render correctly, if used
• Search returns expected results, if used
• Print preview looks correct, if used

Also perform any release-specific checks listed in the release’s upgrade blog post.