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 followed the “Server with Hugo + GitLab Pages”, “Dev client with VSCode” and prepared a server environment built with the GitLab Pages/Hugo template and a development client environment using 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
    ├ .gitlab-ci.yml
    ├ go.mod            ← copy the download
    ├ go.sum            ← copy the download
    └ hugo.toml         ← copy the download
    

    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.toml in Visual Studio Code and change the baseurl to [root URL of the sample site](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_ one.html#project-website-examples).

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_extended is specified in image, change the target of hugo mod get to Docsy, and add npm, PostCSS installation description.

    ...
    image: registry.gitlab.com/pages/hugo/hugo_extended:latest     ← confirm
    
    variables:
      HUGO_ENV: production
      THEME_URL: "github.com/google/docsy"                         ← change
    
    default:
      before_script:
        - apk add --no-cache go curl bash nodejs
        - hugo mod get -u $THEME_URL
        ## Uncomment the following if you use PostCSS...
        - apk add --update npm                                     ← add
        - npm install postcss postcss-cli autoprefixer             ← uncomment
    ...
    
Upload changes made in Visual Studio Code to GitLab

Implement “Upload Hugo repository assets modified in Visual Studio Code to GitLab - Dev client with VSCode”.

Check the build/publish results done automatically in GitLab

Implement “Check the build/publish results done automatically in GitLab - Dev client with VSCode”.

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 informaion, see Source of Docsy.

Remedy

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