Release 0.14.0 report and upgrade guide
- Enhanced internationalization support with updates to Bengali, Serbian, Chinese, and German translations.
- Documentation improvements including Hugo Markdown-style alert support and reorganization.
- Hugo 0.153+ upgrade with breaking changes — see upgrade guide for details.
Release summary
Docsy 0.14.0 comes with the following notable features and improvements:
- Internationalization improvements for multiple locales
- Documentation enhancements including Hugo Markdown-style alert support
- Hugo upgrade to 0.154.5 with important breaking changes
Ready to upgrade?
- Review BREAKING changes:
- Hugo 0.153+ upgrade introduces breaking changes
- Optionally skim:
- New features
- Other notable changes
- When you’re ready, jump to Upgrade to 0.14.0.
Internationalization improvements
This release includes significant improvements to internationalization support:
- Bengali localization: Added feedback section and table of contents translations, fixed newline issues
- Serbian translations: Updated both Cyrillic and Latin variants
- Chinese translations: Updated Simplified and Traditional Chinese locales
- German localization: Completed German translation support
These updates improve the experience for users of Docsy sites in these languages.
Documentation enhancements
Hugo Markdown-style alert support
Docsy 0.14.0 adds support and documentation for Hugo’s native Markdown-style alert syntax. This provides an alternative to the traditional shortcode-based alerts, offering a more Markdown-native approach to creating alerts in your content.
For details about the supported syntax, see Hugo Markdown-style alert support.
Documentation reorganization
The site documentation section has been renamed to “project” section, with pages moved to the About section for better organization. This improves the structure and discoverability of project-related documentation.
Additional documentation improvements
- Added AGENTS.md guide for AI agents working with the Docsy codebase
- Added site build info and build documentation
- Added version badge to documentation pages
- Version tracking added to docs landing page
Hugo upgrade
Docsy 0.14.0 requires Hugo 0.154.5, upgraded from 0.152.2 in Docsy 0.13.0. This upgrade includes several breaking changes introduced in Hugo 0.153+ that may affect your site.
Breaking changes in Hugo 0.153+
Hugo 0.153+ introduces several breaking changes that you should be aware of:
- macOS installations: Hugo installation on macOS needs to be handled differently as of 0.153.0. See issue #2429 for details.
- Default language alias: Changes to default language alias behavior may cause refresh page issues. See gohugoio/hugo#14361 for details.
- Page aliases: Page aliases may refer to the wrong language in some configurations. See issue #2433 for details.
New Hugo features
Hugo 0.154.4+ introduces new features that may be useful:
- Canonical method: New
canonicalmethod available on page output formats. See Hugo documentation. - disableDefaultLanguageRedirect: Configuration option available since Hugo 0.140.0. See Hugo documentation.
Resources for Hugo upgrade
For a comprehensive list of issues and considerations when upgrading to Hugo 0.153+, see Hugo 0.153+ upgrade & issues (#2431). This issue tracks the various problems we’ve encountered (and that other projects might face) during the upgrade process.
Before upgrading, we strongly recommend:
- Review Hugo’s release notes for versions 0.153.0 through 0.154.5
- Test your site with Hugo 0.154.5 in a development environment
- Check for any custom Hugo configurations that might be affected
- Review the Hugo 0.153+ upgrade tracking issue for known issues and workarounds
Other notable changes
- CI/CD improvements: Netlify configuration moved to docsy.dev subrepo, CI cleanup and reorganization
- Package updates: Various npm packages updated alongside the Hugo upgrade
Upgrade to 0.14.0
Prerequisites
We recommend that you Upgrade to Docsy 0.13.0 first because it contains significant breaking changes.
Upgrade procedure
To upgrade from 0.13.0 to 0.14.0, follow the same steps as described in Upgrade to Docsy 0.13.0 from 0.12.0, but use version 0.14.0 instead:
After upgrading, review the breaking changes and test your site thoroughly. Pay special attention to:
- Language aliases: Verify that default language redirects work correctly
- Page aliases: Check that aliases point to the correct language versions
- macOS installations: If you’re on macOS, ensure Hugo is installed correctly
- Build output: Verify that your site builds without errors or warnings
For a testing checklist, see the Upgrade to Docsy 0.13.0 guide.
The Hugo upgrade from 0.152.2 to 0.154.5 includes breaking changes introduced in Hugo 0.153+. Before upgrading, review the Hugo 0.153+ upgrade & issues (#2431) tracking issue for known problems and solutions.
What’s next?
For general work items tentatively planned for future releases, or to track our progress, see Release 0.14.0 preparation (#2404).
If you’d like a feature or fix to be considered for inclusion in an upcoming release, upvote (with a thumbs up) the associated issue or PR.
If you find Docsy useful, consider starring the repository to show your support.
References
About this release:
- 0.14.0 changelog entry
- 0.14.0 release page (when available)
- Release 0.14.0 preparation issue (#2404)
Other references:
- 0.13.0 upgrade guide
- Hugo 0.153+ upgrade & issues (#2431) — comprehensive tracking of Hugo upgrade issues
- For Hugo upgrade considerations when moving from 0.152.2 to 0.154.5, see the Hugo release notes.
These are the officially supported Node.js and Hugo versions associated with the named Docsy versions. Later versions may work, but are not officially supported. ↩︎