This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

About the project

High-level information about the project, including its purpose, ownership, and overall status.

This section is under development.

1 - ReadMe

Docsy repository README

Docsy

Docsy is a Hugo theme for technical documentation sets, providing simple navigation, site structure, and more.

This is not an officially supported Google product. This project is actively being maintained.

Prerequisites

The following are basic prerequisites for using Docsy in your site:

  • Install a recent release of the Hugo “extended” version. If you install from the Hugo release page, make sure you download the extended version, which supports SCSS.

  • Install PostCSS so that the site build can create the final CSS assets. You can install it locally by running the following commands from the root directory of your project:

    npm install --save-dev autoprefixer
npm install --save-dev postcss-cli

    Starting in version 8 of postcss-cli, you must also separately install postcss:

    npm install -D postcss

Any additional prerequisites depend on the installation option you choose. We recommend using Docsy as a Hugo module, which requires that you have the Go language installed in addition to Hugo and PostCSS.

For complete prerequisites and instructions, see our Get started guides.

Example and usage

You can find an example project that uses Docsy in the Docsy Example Project repo.The Docsy Example Project is hosted at example.docsy.dev. For real-life examples of sites that use Docsy (and their source repos), see our Examples and templates page.

To use the Docsy theme for your own site:

  • (Recommended) Use the example project, which includes the Docsy theme as a Hugo module, as a template to create your project. You can customize this pre-configured basic site into your own Docsy themed site. Learn more…

  • Add Docsy to your existing Hugo site. You can add Docsy as a Hugo module, as a Git submodule, or clone the Docsy theme into your project.

See the Get started guides for details about the various usage options.

Documentation

Docsy has its own user guide (using Docsy, of course!) with lots more information about using the theme. It is hosted by Netlify at docsy.dev.

Maintainers: you can access deploy logs, the deploy preview of main, and more from the Deploys section of the site’s Netlify dashboard.

Alternatively you can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:

git clone --depth 1 https://github.com/google/docsy.git
cd docsy
npm install
npm run serve

Contributing

For details on our code of conduct and the process for submitting pull requests, see CONTRIBUTING.md. Thank you to all past, present, and future contributors!

License

This project is licensed under the Apache License 2.0, see LICENSE for details.

2 - Changelog

Docsy repository changelog

We only document breaking changes and release highlights in this page. For the full list of changes of any particular release, see the release notes.

Useful links: Releases & tags, jump to the latest release, and view the milestones.

Style guide

  • Use past tense when when describing releases.
  • Generally, start each change entry with a verb (in the past tense). For example: Added, Changed, Deprecated, Fixed.
  • It’s ok to follow that with “you can now…”. For example:

    Feature abc: you can now…".

  • For additional guidance, see Keep a Changelog1.

Definitions

Definitions...

Public customization surface

As a Hugo theme, Docsy exposes various features that client projects may rely on, such as:

  • Layouts
  • Styles
  • Configuration options
  • Runtime behavior

Aspects of these features are part of Docsy’s public contract, which we also refer to as the public customization surface. We refer to such feature aspects as public for short.

Because Docsy follows semantic versioning, we will not introduce breaking changes to the public customization surface outside of major version releases.2

Private/internal features

Aspects outside the public customization surface are considered private and internal features and implementation details.

Experimental features

Experimental features are not part of the public customization surface and may change or be removed in future releases.

We release experimental features so that projects can try them out and share feedback.

Breaking change

A breaking change is a backward-incompatible change to Docsy’s public contract that requires client projects to update their configuration, content, or customizations in order to:

  • Build successfully (without errors), or
  • Preserve existing, significant site functionality or user experience, including visual design

See semver.

Official support limits

Due to limited resources, official support for Docsy is restricted as follows:

  • Officially released versions of Docsy. The main branch is a development branch and is considered unstable.

  • Each Docsy version only officially supports the following peer package versions, as specified in the theme’s package.json file:

    • Hugo version (hugo-extended)
    • Node.js versions as declared in the engines.node section

  • Operating systems: Linux and macOS.

Any other compatibility (including Windows support) is on a best effort basis.

Next release

UNRELEASED: v0.14.3 or v0.15.0 - still under development

To be completed

For the full list of changes, see the 0.15.0 release page.

Breaking changes:

  • …

New:

  • …

Other changes:

  • …

Experimental:

  • …

v0.14.3

Patch release 0.14.3 applies the layout fix for #2561, which ensures .td-main > .row grows vertically (#2569).

v0.14.2

Key fix for this patch: Apply .td-main flex only when sidebar exists (#2546).

For the full list of changes, see the release report and 0.14.2 release page.

Breaking changes (style-only):

New:

Other changes:

  • Added name attribute to search form field for better semantics and autofill (#2549).
  • Package version build metadata and footer icon tweaks (#2547).

v0.14.1

Patch release 0.14.1: fixed ToC sidebar width in xl viewports (#2538).

v0.14.0

Resources:

Breaking changes:

New:

Other changes:

v0.13.0

Resources:

Breaking changes:

New:

Other changes:

  • Improved accessibility: color contrast and typography (#2285).
  • Dark mode fixes and improvements:
  • Mobile navbar: added scroll indicators for overflow navigation (#2406).
  • Better NPM support: resolved optional and peer dependency issues (#2115). See breaking changes in the blog post.
  • Dependency updates: Bootstrap 5.3.8, Hugo 0.152.2, Node LTS ≥24.
  • Updated translations: added Occitan locale (#2173) and refreshed Simplified Chinese (#2313) and Ukrainian (#2331).
  • TOC visibility control: documented the notoc page parameter (available since 2016) for hiding the table of contents on specific pages (#2405).
  • Build-time rendering of mathematical and chemical formulae: now uses Hugo’s embedded KaTeX engine (#2276, #2394, #2395). For details, see LaTeX support with KaTeX.

Experimental:

v0.12.0

For the full list of changes, see the 0.12.0 release page.

Breaking changes:

  • Renamed the default Docsy heading render hook and heading self-link partials. This is a breaking change only if your project uses this feature. For details, see Heading self links (#2223).
  • Relocated and adapted layouts in response to Hugo’s new template system. For details, see Adapt to new template system in Hugo v0.146.0 #2243.
  • IMPORTANT: if your project overrides any of the layout files mentioned in #2243, then apply the same name changes in your project files. In particular, note that:
    • Taxonomy-related layout files: names have been swapped, and terms.html is now singular (#2257):
      • Renames _default/taxonomy.html to term.html (singular)
      • Renames _default/terms.html to taxonomy.html
    • Renames layouts/**/content.html by adding a _td- filename prefix (#2259).

Potential breaking changes:

  • Removed shortcode figure, hugo’s built-in shortcode figure can/will be used instead.

New:

Other changes:

  • Blog section index page content and title were ignored, they are now displayed (#1787). To recover the old behavior use the following style override: .td-section.td-blog .td-content { display: none; }.
  • Adds a comment shortcode, as a drop-in replacement for the one removed from Hugo’s built-in shortcode.

v0.11.0

For the full list of changes, see the 0.11.0 release page.

New:

v0.10.0

For an introduction to this release, see the 0.10.0 release report. For the full list of changes, see the 0.10.0 release page.

New: color themes and dark-mode support! For details, see Color themes and dark-mode support.

Breaking changes:

  • Removed shortcode card-code that was deprecated in 0.7.0; use shortcode card with named parameter code=true instead.
  • The following SCSS variables are inlined in favor of dark-mode compatible styling: $border-color, $td-sidebar-tree-root-color, $td-sidebar-bg-color, $td-sidebar-border-color (#1952)

Style changes (potentially breaking):

  • Adjusted the style of various shortcodes and elements so that they are compatible with light/dark mode. For details, see Important style changes in Color themes and dark-mode support.

v0.9.1

Patch release. For details, see 0.9.1.

v0.9.0

For an introduction and commentary, see the 0.9.0 release report. For the full list of commits, see the 0.9.0 release page. The most significant changes of this release are listed next.

Breaking changes:

  • Repository Links now work for multi-language sites (#1744).

    For any given page, repository links are now computed from a page’s resolved File path — as resolved through mount points, if any. That is, the path used is the one that refers to the file’s actual location on disk, not its logical path in Hugo’s union file system.

    This is a breaking change for pages of sites that use mounts and path_base_for_github_subdir. Projects will need to adjust the value of path_base_for_github_subdir to be relative to the file’s physical location.

  • Class names to disable repository links were misnamed with a suffix of the form --KIND. The new suffix is __KIND. For details, see Disabling links.

  • Heading self-link support has been reimplemented and projects must now explicitly enable the feature. For details, see Heading self links.

Footer changes: refactoring, for easier customization, and simplification. For details concerning all footer changes, see #1818.

  • Footer layout factored into parts: left, right, and center, with copyright a subpart of center. For details see Footer layout
  • Footer copyright, supports date-range, and site copyright fallback. For details, see Footer copyright.
  • Footer streamlined: the About-page footer link and All-rights-reserved text are now hidden by default. For details, see Footer streamlined.

Other changes:

v0.8.0

For the full list of changes, see the 0.8.0 release page.

Breaking changes:

  • Docsy is packaged as a single Hugo module (#1120). For details, see Use Docsy as a Hugo Module.
  • Important: non-Hugo-module projects should be aware of the Docsy NPM install side-effect. Also, for guidance on Hugo-reported “failed to load modules” error, see Docsy as an NPM package.
  • Page feedback, or User feedback:
    • In support of projects configuring analytics outside of Docsy, feedback functionality is enabled regardless of whether site.Config.Services.GoogleAnalytics.ID is set (#1727).
    • Feedback-event attribute changes (#1726):
      • Event name is page_helpfulrather thanclick
      • Event value for “yes” is 100 by default, rather than 1, allowing for more response options in the future. To override the default set params.ui.feedback.max_value.
  • SCSS: @function prepend() and file assets/scss/support/_functions.scss have been dropped. Instead use the more general SASS/SCSS list join() function (#1385).

v0.7.2

For the full list of changes, see the 0.7.2 release page. We mention some noteworthy changes here:

  • Algolia
    • #1651 DocSearch fixed for mobile and for sites with two search boxes (in the top and left navs).
    • #1662 DocSearch is supported by Docsy through site config.
    • For details, see Algolia DocSearch.
  • Tabbed panes:
    • persistLang is deprecated, use persist instead
    • Persistence is enabled by default (independent of the old persistLang parameter value) ; to disable use persist=disabled
    • Various fixes and enhancements, with more to come; for details, see #1641 and Tabbed panes.
  • Left-nav, and right-nav (TOC + page meta): spacing issues have been resolved; for details, see #1661.

v0.7.1

For the full list of changes, see the 0.7.1 release page.

Followup changes to Bootstrap (BS) 5.2 upgrade (#470):

  • td-blog-posts-list__item and td-blog-posts-list__body replace the .media and .media-body classes, dropped by BS 5 #1560.
  • Docsy test for Bootstrap version has been made more robust, and can be disabled. For details, see #1579.

v0.7.0

For the full list of changes, see the 0.7.0 release page.

New:

  • Click to copy button for Chroma-highlighted code blocks: If you already implemented this functionality on your website, you can disable it. For details see Chroma highlighting docs.

Breaking changes:

  • Hugo release 0.110.0 or later is required.
  • Upgraded Bootstrap (#470) to v5.2. For a list of Bootstrap’s breaking changes, see the Bootstrap migration page. Docsy-specific changes:
    • Clean up of unused, or rarely used, variables, functions, and mixins:
      • Dropped $primary-light
      • Dropped color-diff()
      • Dropped bg-gradient-variant() mixin (#1369)
    • Docsy’s RTL support has been removed because it is incompatible with BSv5. For progress on the reintroduction of RTL support, see #1442.
  • Shortcodes:
    • Now using Hugo’s native support for processing HTML & markdown, not file extension testing. (#906)
    • Dropped support for pre-Hugo-0.54.x behavior of shortcodes with markdown, {{%...%}}. (#939)
    • blocks/section: default and accepted values of the type argument have changed! For details, see blocks/section (#1472).
    • Card shortcodes (#1376)]:
      • Renamed CSS class td-card-deck to td-card-group.
      • card, card-code: markup of inner content (HTML/markdown) now depends on the syntax of the calling shortcode, not on extension of page file any more #906.
      • card-code is deprecated; use card with named parameter code=true instead.
  • Detection of draw.io diagrams is now disabled by default #1185

Other changes:

  • $list-inline-padding is increased in support of footer icons (#1523). If this global adjustment is a problem for your project, let us know and we can contextualize the adjustment to the footer.
  • Non-breaking changes that result from the Bootstrap v5 upgrade:
    • Draw.io diagram edit button: replaced custom colors by BS’s outline primary.

v0.6.0

For the full list of changes, see the 0.6.0 release page.

With this release we declare a feature freeze while we migrate to the newest Bootstrap version. See the announcement for more information.

New:

  • Simplified use of mermaid diagrams: when using a mermaid code block on your page, mermaid is now automatically enabled (needs hugo version >= 0.93.0). For existing sites built with hugo 0.93.0+, parameter mermaid.enable can be removed from site config.

  • Add render hook for chem code blocks: add auto-activation of math and chem blocks via KaTeX and mhchem. Support for formula rendering activation on individual pages only. Hugo version >= 0.93.0 required.

v0.5.1

For the full list of changes, see the 0.5.1 release page. BREAKING CHANGES are documented below.

After you update your project’s Docsy:

  • Update your project setup (see 0.4.0) if you haven’t already.
  • Run npm install.

New:

Breaking changes:

  • Tabbed panes, text display. By default, the content of a tab inside a tabbed pane is shown as code. As of version 0.4 of the shortcode, you can add the parameter code=false to your tabpane or tab shortcode in order to render tab content(s) as text (markdown or html). As of version 0.5 the name of this parameter was changed, we now use text=true in order to mark content as text.
  • Display logo by default. Most projects show their logo in the navbar. In support of this majority, Docsy now displays a logo by default. For details on how to hide the logo (or your brand name), see Styling your project logo and name.
  • Upgraded Bootstrap to v4.6.2 from v4.6.1, resulting in some style changes (such as an adjustment in the size of small). For details, see v4.6.2 release page.
  • Upgraded FontAwesome to v6 from v5. While many icons were renamed, the v5 names still work. For details about icon renames and more, see What’s changed in v6.
  • Search-box: the HTML structure and class names have changed, due to the Font Awesome upgrade, for both online and offline search. This may affect your project if you have overridden search styling or scripts.

Other changes:

v0.5.0

Unpublished.

v0.4.0

For the full list of changes, see the 0.4.0 release page. Potential BREAKING CHANGES are documented below.

After you update your project’s Docsy, run npm install.

Update your project setup:

If your project uses Docsy as follows:

Docsy now fetches Bootstrap and FontAwesome as NPM packages rather than git submodules. This has an impact on your project-build setup. To migrate your site, follow these steps (execute commands from your project’s root directory):

  1. Delete obsolete Docsy Git submodules:
    git rm themes/docsy/assets/vendor/Font-Awesome
git rm themes/docsy/assets/vendor/bootstrap
    These commands remove the submodules from Git’s tracking, from the .gitmodules file, and deletes the submodule files under themes/docsy/assets/vendor.
  2. Get Docsy dependencies:
    (cd themes/docsy && npm install)
  3. Update your build scripts to fetch Docsy dependencies automatically. For example, if your site build uses NPM scripts, consider getting Docsy dependencies via a prepare script as follows:
    {
  "name": "my-website",
  "scripts": {
    "prepare": "cd themes/docsy && npm install",
    "...": "..."
  },
  "...": "..."
}
  4. (Optional) Build script cleanup. If your project uses Docsy as a git submodule, Docsy updates no longer require the --recursive flag when running git submodule update. Consider dropping the flag if you have no other recursive git submodules.

Proceed as usual to build or serve your site.

v0.3.0

For the full list of changes, see the 0.3.0 release page.

Breaking changes:

v0.2.0

For the full list of changes, see the 0.2.0 release page.

New:

  1. Old entries might not follow this guidance; feel free to update them as needed. ↩︎

  2. Docsy is not yet at version 1.0.0, so we are bound by the pre-v1 semantic versioning rules. We treat minor releases as if they were major releases. ↩︎

3 - Maintainer notes

Notes for Docsy maintainers

For our main contributing page covering license agreements, code of conduct and more, see Contributing. This page is for maintainers only.

Publishing a release

These notes are WIP for creating a release from a local copy of the repo. These instructions assume the release is v0.14.4-dev, if not adjust accordingly.

  1. Change directory to your local Docsy repo.

  2. Create or update a changelog entry for v0.14.4-dev.

    • The section should provide a brief summary of breaking changes using the section template at the end of the file.
    • Ensure to remove the UNRELEASED note, if still present.
    • You’ll create a new section for the next release in a later step.

  3. Update the release report blog post for v0.14.4-dev, if any.

    • Remove draft status.
    • Set date (or lastmod if already published) to today’s date.

  4. Run npm run fix.

  5. Update Docsy version to v0.14.4-dev using the following from a (bash or zsh) terminal.

    • First set the VERSION variable; we use it throughout the steps below.

      VERSION=v0.14.4-dev

    • Then run the set:version script.

      Docsy is probably already at v0.14.4-dev-dev, so you can run:

      npm run set:version

      Otherwise, set the version explicitly:

      npm run set:version -- --version $VERSION

      Both forms update the version related fields in package.json and docsy.dev/config files.

  6. Run npm run ci:test, which runs ci:prepare and more to ensure that, e.g., vendor assets and go.mod dependencies are up-to-date, etc.

  7. Submit a PR with your changes.

    • Set the BASE variable to the target branch: main if this is a stable release, and release for patch releases.

      BASE=main

    • Commit any changes accumulated from the previous steps using this title:

      Release v0.14.4-dev preparation

    • Create a PR (with version-checks disabled) using the following command that will open a PR-creation page in your browser:

      export SKIP_VERSION_CHECK=1
gh pr create --web --title "Release $VERSION preparation" \
  --base $BASE \
  --body "- Contributes to #<ADD-RELEASE-PREP-ISSUE-HERE>"

    • Use the web interface to fill in the PR details.

    • Submit the PR.

  8. Test the PR branch from selected sites, and push any required adjustments.

    • If the test site uses Docsy as a Git submodule:

      cd themes/docs
git fetch
git switch -t REPO/BRANCH-NAME # e.g. chalin/chalin-m24-0.14.0-pre-release

  9. Get PR approved and merged.

  10. Pull the PR to get the last changes.

  11. Test Docsy from docsy-example, for example.

  12. Ensure that you’re:

    • On the target $BASE branch
    • At the commit that you want to tag as v0.14.4-dev

  13. Create the new tag for v0.14.4-dev.

    • Set the REL variable to the release version or use the VERSION variable if you set it in the previous step.

      REL=v${VERSION:-v0.14.4-dev}
echo "REL=$REL"

    • Create the new tag.

      git tag $REL

    • Double check:

      git tag --sort=-creatordate | head -3

  14. Push the new tag: either to all remotes at once, or one at a time.

    Push to all remotes

    • List the remotes so you know what you’ll be pushing to:

      git remote

    • Check that the push-all-remotes alias is defined, and if not, define it:

      git config --global --list | grep alias.push-all-remotes
      Define a `push-all-remotes` alias

      First check if the push-all-remotes alias is already defined:

      git config --global --list | grep alias.push-all-remotes

      If not, define the alias:

      git config --global alias.push-all-remotes \
  '!f() { for r in $(git remote); do (set -x; git push "$r" "$1"); done; }; f'

    • If you have git hooks enabled that auto-update the Docsy package version, disable the hook check for now:

      export SKIP_VERSION_CHECK=1

    • Push the tag to the remotes:

      $ git push-all-remotes $REL
+ git push origin v0.14.4-dev
* [new tag]         v0.14.4-dev -> v0.14.4-dev
+ git push upstream v0.14.4-dev
* [new tag]         v0.14.4-dev -> v0.14.4-dev
...

    • Sanity check over upstream for example:

      git ls-remote --tags upstream | grep $REL

    • Unset the SKIP_VERSION_CHECK variable when you’re done:

      unset SKIP_VERSION_CHECK
    Push to a single remote
    • Push to a single remote at a time, such as upstream:
    git push upstream $REL

    • Sanity check over upstream for example:

      git ls-remote --tags upstream | grep $REL

  15. Update the deploy/prod branch from $BASE.

    For stable releases from main, use:

    git checkout deploy/prod
git merge --ff-only main
git push-all-remotes deploy/prod

    For patch releases from release, selectively merge from $BASE.

    The branch update will trigger a production deploy of the website.

  16. Wait for the production deploy to complete and check that docsy.dev has been updated to the new release.

  17. Draft a new release using GitHub web; fill in the fields as follows:

    • Visit tags to find the new release tag v0.14.4-dev.

    • Select Create a new release from the v0.14.4-dev tag dropdown menu

    • Release title: use the release version.

      v0.14.4-dev

    • Click Generate release notes to get the release details inserted into the release notes text area.

    • Add the following text atop the generated release notes:

      ## Release summary

- [Release 0.14.0 report and upgrade guide][blog]
- [Changelog v0.14.4-dev][changelog] entry


[blog]: <https://www.docsy.dev/blog/2026/0.14.0/>
[changelog]: <https://www.docsy.dev/project/about/changelog/#0.14.4-dev>

    • Select Create a discussion for this release.

  18. Publish the release: click Publish release.

  19. Test the release with a downstream project and/or the docsy-example site.

  20. If you find issues, determine whether they need to be fixed immediately. If so, get fixes submitted, reviewed and approved. Go back to step 1 to publish a dot release.

If all is well, release the Docsy example as detailed next.

Docsy example release

The steps you follow are similar to the ones above for the Docsy release, but with the following modifications:

  1. Update the version of the example to v0.14.4-dev:

    VERSION=v0.14.4-dev
npm run set:version:example -- --version $VERSION

  2. Perform step 6 onwards as above to test, create a PR, create a release and publish it with one difference:

    • To create a new release draft, visit Docsy-example release draft.
    • Once the deploy/prod branch has been updated, wait for the production deploy to complete and check that example.docsy.dev has been updated to the new release.

Post Docsy-release followup

Assuming that both the Docsy and Docsy-example releases v0.14.4-dev have been successfully deployed, and that at least one other project has been successfully tested with the new release, then perform the following actions before any further changes are merged into the main branch:

  1. Update the package version to a dev ID for Docsy and Docsy-example:

    $ npm run -s set:version:git-info
✓ Updated package.json version: 0.14.3 → 0.14.3-dev+003-over-main-cf4f514b
✓ Updated docsy.dev/config/_default/params.yaml version: 0.14.3 → 0.14.3-dev
✓ Updated docsy.dev/config/_default/params.yaml tdBuildId: (none) → 003-over-main-cf4f514b
...
$ npm run -s set:version:example:git-info
...

  2. In the Changelog:

    • Create a new entry for the next release by copying the ENTRY TEMPLATE at the end of the file.

    • Fix the new release URL, which ends with latest?FIXME=..., so that it refers to the actual release, now that it exists.

  3. Submit a PR with your changes, using a title like:

    Set version to v0.14.4-dev

  4. Get PR approved and merged.

Release helper scripts

  • NPM scripts: set:version and set:version:*
  • scripts/get-build-id.sh: Generates build ID from git describe (empty on tags).
  • scripts/set-package-version/index.mjs: Low-level version manager. See script help for usage.