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

Return to the regular view of this page.

Update Docsy

Keeping the Docsy theme up to date.

We hope to continue to make improvements to the theme along with the Docsy community. If you have cloned the example site (or are otherwise using the theme as a Hugo Module or Git submodule), you can easily update the Docsy theme in your site yourself. If you have cloned the theme itself into your own project you can also update, though you may need to resolve merge conflicts.

Updating Docsy means that your site will build using the latest version of Docsy at HEAD and include all the new commits or changes that have been merged since the point in time that you initially added the Docsy submodule, or last updated. Updating won’t affect any modifications that you made in your own project to override the Docsy look and feel, as your overrides don’t modify the theme itself. For details about what has changed in the theme since your last update, see the list of Docsy commits.

If you have been using the theme as a Git submodule, you can also update your site to use Docsy as a Hugo Module. This is the latest and simplest way to pull in a Hugo theme from its repository. If you’re not ready to migrate to Hugo Modules yet, don’t worry, your site will still work and you can continue to update your submodule as before.

1 - Update the Docsy Hugo Module

Update the Docsy theme to the latest version using Hugo Modules.

When using the Docsy theme as a Hugo Module, updating your theme is really easy.

At the command prompt, change to the root directory of your existing site.

cd /path/to/my-existing-site

Then invoke hugo’s module get subcommand with the update flag:

hugo mod get -u github.com/google/docsy

Hugo automatically pulls in the latest theme version. That’s it, your update is done!

2 - Update Docsy without Hugo Modules

Update the Docsy theme to the latest version using submodules or git pull.

If you aren’t using Hugo Modules, depending on how you chose to install Docsy on your existing site, use one of the following two procedures to update your theme.

Update your Docsy submodule

If you are using the Docsy theme as a submodule in your project, here’s how you update the submodule:

  1. Navigate to the root of your local project, then run:

     git submodule update --remote

  2. Add and then commit the change to your project:

     git add themes/
 git commit -m "Updating theme submodule"

  3. Push the commit to your project repo. For example, run:

     git push origin master

Route 2: Update your Docsy clone

If you cloned the Docsy theme into the themes folder in your project, then you use the git pull command:

  1. Navigate to the themes directory in your local project:

     cd themes

  2. Ensure that origin is set to https://github.com/google/docsy.git:

     git remote -v

  3. Update your local clone:

     git pull origin master

If you have made any local changes to the cloned theme, you must manually resolve any merge conflicts.

3 - Migrate to Hugo Modules

Convert an existing site to use Docsy as a Hugo Module

TL;DR: Conversion for the impatient expert

Run the following from the command line:

cd /path/to/my-existing-site
hugo mod init github.com/me-at-github/my-existing-site
hugo mod get github.com/google/docsy@0.2.0-pre
hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
sed -i '/theme = \["docsy"\]/d' config.toml
cat >> config.toml <<EOL
[module]
[[module.imports]]
path = "github.com/google/docsy"
[[module.imports]]
path = "github.com/google/docsy"
EOL
hugo server
cd  my-existing-site
hugo mod init github.com/me-at-github/my-existing-site
hugo mod get github.com/google/docsy@0.2.0-pre
hugo mod get github.com/google/docsy/dependencies@0.2.0-pre
findstr /v /c:"theme = [\"docsy\"]" config.toml > config.toml.temp
move /Y config.toml.temp config.toml
(echo [module]^

[[module.imports]]^

path = "github.com/google/docsy"^

[[module.imports]]^

path = "github.com/google/docsy")>>config.toml
hugo server

Detailed conversion instructions

Import the Docsy theme module as a dependency of your site

At the command prompt, change to the root directory of your existing site.

cd /path/to/my-existing-site

Only sites that are Hugo Modules themselves can import other Hugo Modules. Turn your existing site into a Hugo Module by running the following command from your site directory, replacing github.com/me/my-existing-site with your site repository:

hugo mod init github.com/me/my-existing-site

This creates two new files, go.mod for the module definitions and go.sum which holds the checksums for module verification.

Next declare the Docsy theme module as a dependency for your site. You must also declare the submodule dependencies as a second dependency. This submodule pulls in both a workaround for a bug in Go’s module management and the dependencies bootstrap and Font-Awesome.

hugo mod get github.com/google/docsy@0.2.0-pre
hugo mod get github.com/google/docsy/dependencies@0.2.0-pre

These commands add both the docsy theme module and the dependencies submodule to your definition file go.mod.

Update your config file

In your config.toml file, update the theme setting to use Hugo Modules. Find the following line:

theme = ["docsy"]

Change this line to:

theme = ["github.com/google/docsy", "github.com/google/docsy/dependencies"]

Alternatively, you can omit this line altogether and replace it with the settings given in the following snippet:

[module]
  # uncomment line below for temporary local development of module
  # replacements = "github.com/google/docsy -> ../../docsy"
  [module.hugoVersion]
    extended = true
    min = "0.73.0"
  [[module.imports]]
    path = "github.com/google/docsy"
    disable = false
  [[module.imports]]
    path = "github.com/google/docsy/dependencies"
    disable = false
module:
  hugoVersion:
    extended: true
    min: 0.73.0
  imports:
    - path: github.com/google/docsy
      disable: false
  imports:
    - path: github.com/google/docsy/dependencies
      disable: false
{
  "module": {
    "hugoVersion": {
      "extended": true,
      "min": "0.73.0"
    },
    "imports": [
      {
        "path": "github.com/google/docsy",
        "disable": false
      },
      {
        "path": "github.com/google/docsy/dependencies",
        "disable": false
      }
    ]
  }
}

Check validity of your configuration settings

To make sure that your configuration settings are correct, run the command hugo mod graph which prints a module dependency graph:

hugo mod graph
hugo: collected modules in 1092 ms
github.com/me/my-existing-site github.com/google/docsy@0.2.0-pre
github.com/me/my-existing-site github.com/google/docsy/dependencies@0.2.0-pre
github.com/google/docsy/dependencies@0.2.0-pre github.com/twbs/bootstrap@v4.6.1+incompatible
github.com/google/docsy/dependencies@0.2.0-pre github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac

Make sure that three lines with dependencies docsy, bootstrap and Font-Awesome are listed. If not, please double check your config settings.

Clean up your repository

Since your site now uses Hugo Modules, your previously used themes directory can be removed:

rm -rf /path/to/your/theme

If your Docsy theme was installed as submodule, you can remove the theme submodule:

git rm --cached /path/to/your/submodule/theme
git add .

With your submodule deleted, now delete the relevant line from the hidden submodule definition file .gitmodules, too. If this is the only line, you can delete the file altogether.

rm .gitmodules

Finally, delete the now untracked submodule files and also clean up the internal directory that git used to store your git submodules:

rm -rf /path/to/your/submodule/theme
rm -rf .git/modules