Apply Docsy
Tags: hugo, jamstack, tutorial
Published: 2022-07-23 14:23:00

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.

![Blogging environment with Hugo + GitLab Pages : Hugo theme/content repository position and file structure](https://ayaco.gitlab.io/zerogravity/en/docs/theme/docsy-apply/feature.svg)

## Assumption

This explanation assumes that you have followed the "[Server with Hugo + GitLab Pages](https://ayaco.gitlab.io/zerogravity/en/docs/setup/server/)", "[Dev client with VSCode](https://ayaco.gitlab.io/zerogravity/en/docs/setup/client/)" 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`.

1. Open [Docsy sample project](https://github.com/google/docsy-example) 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.

1. 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.

1. Open [.gitlab-ci.yml for GitLab Pages/Hugo template](https://gitlab.com/pages/hugo/-/blob/main/.gitlab-ci.yml) in your browser, download it, and copy it to the `/` of the Hugo repository assets you manage in Visual Studio Code.

1. 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](https://ayaco.gitlab.io/zerogravity/en/docs/setup/client/#upload-hugo-repository-assets-modified-in-visual-studio-code-to-gitlab)".

### Check the build/publish results done automatically in GitLab

Implement "[Check the build/publish results done automatically in GitLab - Dev client with VSCode](https://ayaco.gitlab.io/zerogravity/en/docs/setup/client/#check-the-buildpublish-results-done-automatically-in-gitlab)".

## Troubleshooting

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

#### Phenomenon

If you [apply the theme as a Hugo Module](https://www.docsy.dev/) instead of [apply by Git submodule or other method](https://www.docsy.dev/docs/get-started/other-options/) 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](https://gitlab.com/pages/hugo/-/issues/84) 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](https://gitlab.com/pages/hugo/-/merge_requests/184) 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](https://github.com/google/docsy/commit/33f3dfe384636c8f102d2f7980e365be58999b1e#diff-ed3b5a25a9efb89d0cebc442bd8b68c2b2caa45746f6633f89aa4a0e45410f9a).

#### Remedy

Delete the definition of `[params.mermaid]` in `hugo.config`.
For more information, see [Discussion of Docsy](https://github.com/google/docsy/discussions/1588).