Update Docsy

• 1: Update your Docsy Hugo Module
• 2: Update your Docsy NPM package
• 3: Update your Docsy Git submodule or clone
• 4: Migrate to Hugo Modules

nvm install NODE_VERSION

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

1 - Update your Docsy Hugo Module

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/theme

Hugo automatically pulls in the latest theme version.

hugo mod get github.com/google/docsy/theme@v0.16.0

hugo mod get github.com/google/docsy/theme@9b1d9951

After updating the theme, tidy your module files, refresh the theme npm dependencies that are consolidated into your site’s package.json, and reinstall them:

hugo mod tidy
hugo mod npm pack
npm install

Hugo warns at build time when your package.json dependency set has drifted from the theme’s. To verify the resolved version, run:

hugo mod graph

Confirm that it lists github.com/google/docsy/theme at the version you expect.

After updating the theme, continue with the remaining update steps, starting with Review your theme overrides.

2 - Update your Docsy NPM package

Update the theme to the latest release by running the following from your project root:

npm install --save-dev @docsy/theme@latest

npm install --save-dev @docsy/theme@v0.16.0

To verify the resolved version of @docsy/theme, run:

npm ls @docsy/theme --depth=0

If your site installs Docsy from GitHub with npm (a mode reserved for Docsy development and testing), update by re-running the install command with the desired revision selector.

After updating the theme, continue with the remaining update steps, starting with Review your theme overrides.

3 - Update your Docsy Git submodule or clone

Use the procedure matching how Docsy was installed in your project: submodule or clone.

Update your Docsy submodule

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

1. Navigate to the root of your local project, then update the submodule to the release tag that you are targeting, for example:

   git -C themes/docsy fetch --tags
   git -C themes/docsy checkout v0.16.0
   

2. Reinstall the theme’s runtime dependencies:

   npm run postinstall --prefix themes/docsy
   

   Run npm run postinstall, not npm install; for why, see the setup note.

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

   git add themes/docsy
   git commit -m "Update Docsy theme to v0.16.0"
   

4. Push the commit to your project repo.

Update your Docsy clone

If you cloned the Docsy theme into the themes folder in your project, update the clone to the release tag that you are targeting:

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

   git -C themes/docsy fetch --tags
   git -C themes/docsy checkout v0.16.0
   

   Ensure that origin is set to https://github.com/google/docsy.git (git -C themes/docsy remote -v).

2. Reinstall the theme’s runtime dependencies:

   npm run postinstall --prefix themes/docsy
   

   As in the submodule procedure, run npm run postinstall, not npm install.

3. Persist the update to your project, the same way that your project already tracks the cloned theme: for example, commit the updated theme files to your project repository, or record the new tag where your build restores the clone from.

If you have local changes in the cloned theme, commit or stash them first: checking out a tag fails on uncommitted changes, and detaches HEAD from any local branch. After checking out the new tag, reapply your changes (for example, git stash pop, or rebase your branch onto the tag), resolving any conflicts.

After updating the theme, continue with the remaining update steps, starting with Review your theme overrides.

4 - 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/theme@v0.16.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/theme"
EOL
hugo mod npm pack
npm install
hugo server

cd  my-existing-site
hugo mod init github.com/me-at-github/my-existing-site
hugo mod get github.com/google/docsy/theme@v0.16.0
findstr /v /c:"theme = [\"docsy" config.toml > hugo.toml
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/google/docsy/theme")>>hugo.toml
hugo mod npm pack
npm install
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/theme@v0.16.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 (docsy/theme if your site is on Docsy 0.16 or later, docsy otherwise):

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

theme = ["docsy/theme"]

theme: docsy/theme

"theme": "docsy/theme"

Change this line to:

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

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

theme:
  - github.com/google/docsy/theme

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

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/theme -> ../../docsy/theme"
  [module.hugoVersion]
    extended = true
    min = 0.160.1
  [[module.imports]]
    path = "github.com/google/docsy/theme"
    disable = false

module:
  proxy: direct
  hugoVersion:
    extended: true
    min: 0.160.1
  imports:
    - path: github.com/google/docsy/theme
      disable: false

{
  "module": {
    "proxy": "direct",
    "hugoVersion": {
      "extended": true,
      "min": 0.160.1
    },
    "imports": [
      {
        "path": "github.com/google/docsy/theme",
        "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.

Install theme npm dependencies

Docsy sources its Bootstrap and Font Awesome assets from npm. Consolidate the theme’s npm dependencies into your project’s package.json and install them:

hugo mod npm pack
npm install

Re-run hugo mod npm pack whenever you update Docsy; Hugo warns when the dependency set drifts. For background, see Bootstrap and Font Awesome via npm in the 0.16.0 release notes.

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/theme@v0.16.0

Make sure that the docsy/theme dependency is 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/google/docsy/theme"

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"