Update Docsy

• 1: Update your Docsy Hugo Module
• 2: Update Docsy without Hugo Modules
• 3: Migrate to Hugo Modules

1 - Update your Docsy Hugo Module

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!

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

hugo mod get -u github.com/google/docsy@6c8a3afe

2 - Update Docsy without Hugo Modules

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

TL;DR: Conversion for the impatient expert

Run the following from the command line:

• CLI:
• Unix shell
• Windows 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@v0.11.0
sed -i '/theme = \["docsy"\]/d' config.toml
mv config.toml hugo.toml
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[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@v0.11.0
findstr /v /c:"theme = [\"docsy\"]" config.toml > hugo.toml
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/google/docsy")>>hugo.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.

hugo mod get github.com/google/docsy@v0.11.0

This command adds the docsy theme module to your definition file go.mod.

Update your config file

In your hugo.toml/hugo.yaml/hugo.json file, update the theme setting to use Hugo Modules. Find the following line:

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

theme = ["docsy"]

theme: docsy

"theme": "docsy"

Change this line to:

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

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

theme:
  - github.com/google/docsy

"theme": [
  "github.com/google/docsy"
]

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

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[module]
  proxy = "direct"
  # 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:
  proxy: direct
  hugoVersion:
    extended: true
    min: 0.73.0
  imports:
    - path: github.com/google/docsy
      disable: false
    - path: github.com/google/docsy/dependencies
      disable: false

{
  "module": {
    "proxy": "direct",
    "hugoVersion": {
      "extended": true,
      "min": "0.73.0"
    },
    "imports": [
      {
        "path": "github.com/google/docsy",
        "disable": false
      },
      {
        "path": "github.com/google/docsy/dependencies",
        "disable": false
      }
    ]
  }
}

You can find details of what these configuration settings do in the Hugo modules documentation. Depending on your environment you may need to tweak them slightly, for example by adding a proxy to use when downloading remote modules.

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@v0.11.0
github.com/google/docsy@v0.11.0 github.com/twbs/bootstrap@v5.2.3+incompatible
github.com/google/docsy@v0.11.0 github.com/FortAwesome/Font-Awesome@ v0.0.0-20230802202706-f0c25837a3fe

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

hugo mod clean
hugo: collected modules in 995 ms
hugo: cleaned module cache for "github.com/FortAwesome/Font-Awesome"
hugo: cleaned module cache for "github.com/google/docsy"
hugo: cleaned module cache for "github.com/twbs/bootstrap"

Clean up your repository

Since your site now uses Hugo Modules, you can remove docsy from the themes directory, as instructed below. First, change to the root directory of your site:

cd /path/to/my-existing-site

Previous use of Docsy theme as git clone

Simply remove the subdirectory docsy inside your themes directory:

rm -rf themes/docsy

Previous use of Docsy theme as git submodule

If your Docsy theme was installed as submodule, use git’s rm subcommand to remove the subdirectory docsy inside your themes directory:

git rm -rf themes/docsy

You are now ready to commit your changes to your repository:

git commit -m "Removed docsy git submodule"