Apply Universal

Learn how to apply the Hugo's "Universal" 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 Universal, replace the theme settings/content with the Universal sample, change the CI/CD settings for Universal, 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. Create a symbolic link to the Universal repository under /themes in the Hugo repository assets managed by Visual Studio Code by running the following in the Visual Studio Code terminal.
   

   > cd (the root directory of the Git project)
   > mkdir themes
   > git submodule add https://github.com/devcows/hugo-universal-theme.git themes/hugo-universal-theme
   

3. Copy /themes/hugo-universal-theme/* in the Hugo repository assets managed by Visual Studio Code to /.
   

   Hugo repository assets
   ├ content           ← copy from exampleSite
   ├ data              ← copy from exampleSite
   ├ static            ← copy from exampleSite
   ├ themes
   ├ .gitlab-ci.yml
   ├ .gitmodules
   └ config.toml       ← copy from exampleSite
   

4. Open /config.toml in Visual Studio Code and change baseurl to root URL of the sample site.

Caution
: ""Error: failed to load modules:..." when applying theme" may need to be addressed.

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, change image to non hugo:std, comment out the hugo mod description and add a git submodule description.
   

   ...
   image: hugomods/hugo:std                        ← change (hugo:exts is also acceptable)
   ...
   default:
     before_script:
   #   - hugo mod get -u $THEME_URL                ← comment out
       - git submodule update --init --recursive   ← 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

Phenomenon

When applying a theme using /themes/hugo-universal-theme/exampleSite/config.toml, the following error occurs.

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

Cause

Error in themesDir in config.toml. The value has been set to "../..".

Remedy

Correct the value of themesDir in config.toml to "themes".

    ...
    themesDir = "themes"
    ...