DEV Community

Cover image for Apply Universal
ayaco
ayaco

Posted on • Originally published at ayaco.gitlab.io

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.

Blogging environment with Hugo + GitLab Pages : Hugo theme/content repository position and file structure

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
Enter fullscreen mode Exit fullscreen mode

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"
    ...
Enter fullscreen mode Exit fullscreen mode

Top comments (0)