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 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. 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_extended, comment out the hugo mod description and add a git submodule description.
   

   ...
   image: registry.gitlab.com/pages/hugo:latest                   ← change
   
   variables:
     HUGO_ENV: production
     #THEME_URL: "github.com/theNewDynamic/gohugo-theme-ananke"   ← comment out
   
   default:
     before_script:
       - apk add --no-cache go curl bash nodejs
       - git submodule update --init --recursive                  ← add
       #- hugo mod get -u $THEME_URL                              ← comment out
       ## Uncomment the following if you use PostCSS...
       #- npm install postcss postcss-cli autoprefixer
   ...
   

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

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