Migrate to Hugo Modules

TL;DR: Conversion for the impatient expert

Run:

• 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
[ -f config.toml ] && mv config.toml hugo.toml
sed -i.bak '/theme = \["docsy/d' hugo.toml && rm hugo.toml.bak
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy/theme"
EOL
npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run 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
if exist config.toml ren config.toml hugo.toml
findstr /v /c:"theme = [\"docsy" hugo.toml > hugo.toml.tmp
move /y hugo.toml.tmp hugo.toml
(echo [module]^

proxy = "direct"^

[[module.imports]]^

path = "github.com/google/docsy/theme")>>hugo.toml
npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo
hugo mod npm pack
npm install
npm run hugo -- server

Detailed conversion instructions

Import the Docsy theme module as a dependency of your site

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-at-github/my-existing-site with your site repository:

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

This creates a go.mod file for your site’s module definitions.

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 and records the module checksums in go.sum.

Update your config file

If your site still uses a config.toml file, rename it to hugo.toml first.

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

Follow Install Dart Sass so that Hugo runs with the sass CLI on its PATH; for npm-based sites, that means installing the tested sass-embedded version and running Hugo through npm scripts:

npm install --save-exact --save-dev sass-embedded@1.102.0
npm pkg set scripts.hugo=hugo

Docsy sources its Bootstrap and Font Awesome assets from npm. Generate the theme’s npm-dependency workspace (see Hugo’s Node dependencies) and install it:

hugo mod npm pack
npm install

Re-run hugo mod npm pack whenever you update Docsy or otherwise edit package.json; 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

Run hugo mod graph and verify that it lists github.com/google/docsy/theme:

hugo mod graph
hugo: collected modules in 1092 ms
github.com/me-at-github/my-existing-site github.com/google/docsy/theme@v0.16.0

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, remove the docsy theme copy from your project’s themes/ directory:

• For a theme clone:

  rm -rf themes/docsy
  

• For a theme submodule:

  git rm -rf themes/docsy
  

Then commit the change:

git commit -m "Removed docsy git submodule"