Apply Docsy

Learn how to apply the Hugo’s “Docsy” theme.

Goal

Below are the components of a blogging environment with Hugo + GitLab Pages.
The goal here is to change the theme body in the GitLab Hugo theme/content repository to Docsy, replace the theme settings/content with the Docsy sample, change the CI/CD settings for Docsy, and build/publish the sample site.

Assumption

This explanation assumes that you have a server environment with GitLab Pages/Hugo templates and a development client environment with Visual Studio Code.

Application method

Modify theme body, theme settings/contents in Visual Studio Code

1. Delete all Hugo repository assets managed by Visual Studio Code except for /.gitlab-ci.yml.

2. Open Docsy sample project in your browser, download all files and copy them to / of your Hugo repository assets managed by Visual Studio Code.
   

   Hugo repository assets
   ├ assets           ← copy the download
   ├ content          ← copy the download
   ├ layouts          ← copy the download
   ├ hugo.yaml        ← copy the download
   ├ go.mod           ← copy the download
   ├ go.sum           ← copy the download
   └ .gitlab-ci.yml
   

   Note that the theme body /themes is not registered as a Hugo repository asset.
   It will be dynamically imported at build time by subsequent CI/CD configuration changes.

3. Open /hugo.yaml in Visual Studio Code and change the baseurl to root URL of the sample site.

Change CI/CD settings in Visual Studio Code to match the theme

1. Delete /.gitlab-ci.yml in the Hugo repository assets managed by Visual Studio Code.

2. Open .gitlab-ci.yml for GitLab Pages/Hugo template in your browser, download it, and copy it to the / of the Hugo repository assets you manage in Visual Studio Code.

3. Open /.gitlab-ci.yml in Visual Studio Code, make sure hugo:exts is specified in image, change THEME_URL to Docsy, and add PostCSS installation description.
   

   ...
   image: hugomods/hugo:exts                              ← confirm
   
   variables:
     HUGO_ENV: production
     THEME_URL: "github.com/google/docsy"                 ← change
   
   default:
     before_script:
       - hugo mod get -u $THEME_URL
       - npm install postcss postcss-cli autoprefixer     ← add
   ...
   

Upload changes made in Visual Studio Code to GitLab

Upload the modified assets to GitLab using Visual Studio Code in your browser.

Check the build/publish results done automatically in GitLab

Check build/publish results.

Troubleshooting

"Error: failed to load modules:..." when applying theme as Hugo Module

Phenomenon

If you apply the theme as a Hugo Module instead of apply by Git submodule or other method docs/get-started/docsy-as-module/), the following error occurs.

: Error: failed to load modules: module "..." not found in "..."; either add it as a Hugo Module or store it in "...".: module does not exist

Cause

Due to some changes in Hugo, higo mod init in GitLab CI/CD seems to cause an error.
See Issue of GitLab Pages exaples for details.

This issue did not occur until Hugo V0.109.0, so it seems to be caused by a change in V0.110.0 or later.

Remedy

Delete higo mod init in .gitlab-ci.yml and register the locally generated go.mod and go.sum in the repository beforehand.
See Merge request for GitLab Pages exaples for details.

If you are in a hurry, you can also specify Hugo V0.109.0 (the version that worked reliably) in .gitlab-ci.yml.

...
image: registry.gitlab.com/pages/hugo/hugo_extended:0.109.0
...

Mermaid script is always loaded

Phenomenon

Mermaid script is always loaded on the page, regardless of whether mermaid is used or not, incurring unnecessary loading costs.

<script src="https://cdn.jsdelivr.net/npm/mermaid@9.3.0/dist/mermaid.min.js" integrity="sha512-ku2nmBrzAXY5YwohzTqLYH1/lvyMrpTVxgQKrvTabd/b/uesqltLORdmpVapYv6QhZVCLUX6wkvFaKOAY4xpUA==" crossorigin="anonymous"></script>

Cause

Due to specification changes in Docsy V0.7.0.
Just having a definition of [params.mermaid] in hugo.config now enables mermaid, even if enable=false.

[params.mermaid]
enable = false

For more information, see Source of Docsy.

Remedy

Delete the definition of [params.mermaid] in hugo.config.
For more information, see Discussion of Docsy.