Issue with CSS Not Loading for a Hugo Website Deployed with GitHub Pages

3 min read

Deploying a Hugo website on GitHub Pages is a seamless process, thanks to the comprehensive documentation provided here. However, I recently encountered an issue where my Hugo website launched successfully but failed to load the CSS.

The Problem

Upon checking the developer console, I noticed the following error:

text 
1https://namanattri.dev/namanattri.dev/ananke/css/main.min.css 404

It was clear that the path to the CSS was incorrect. The generated HTML included the following line:

html 
1<link rel="stylesheet" href="/namanattri.dev/ananke/css/main.min.css">

The base path namanattri.dev was being prepended to the theme CSS path incorrectly. The correct URL should have been:

html 
1https://namanattri.dev/ananke/css/main.min.css

This would correspond to the following HTML:

html 
1<link rel="stylesheet" href="/ananke/css/main.min.css">

Investigating the Issue

The config.toml file already had the correct baseURL set:

toml 
1baseURL = 'https://namanattri.dev/'
2languageCode = 'en-us'
3title = 'Naman Attri'
4theme = 'ananke'

Upon further investigation, I realized the GitHub workflow file suggested by the documentation was passing --baseURL "${{ steps.pages.outputs.base_url }}/" to the Hugo command:

yaml 
1run: |
2  hugo \
3    --gc \
4    --minify \
5    --baseURL "${{ steps.pages.outputs.base_url }}/"

This was causing the baseURL to be appended incorrectly.

The Solution

Removing --baseURL "${{ steps.pages.outputs.base_url }}/" from the workflow file fixed the issue. Here is the corrected workflow file:

yaml 
 1# Sample workflow for building and deploying a Hugo site to GitHub Pages
 2name: Deploy Hugo site to Pages
 3
 4on:
 5  # Runs on pushes targeting the default branch
 6  push:
 7    branches:
 8      - main
 9
10  # Allows you to run this workflow manually from the Actions tab
11  workflow_dispatch:
12
13# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
14permissions:
15  contents: read
16  pages: write
17  id-token: write
18
19# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
20# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
21concurrency:
22  group: "pages"
23  cancel-in-progress: false
24
25# Default to bash
26defaults:
27  run:
28    shell: bash
29
30jobs:
31  # Build job
32  build:
33    runs-on: ubuntu-latest
34    env:
35      HUGO_VERSION: 0.128.0
36    steps:
37      - name: Install Hugo CLI
38        run: |
39          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
40          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
41      - name: Install Dart Sass
42        run: sudo snap install dart-sass
43      - name: Checkout
44        uses: actions/checkout@v4
45        with:
46          submodules: recursive
47          fetch-depth: 0
48      - name: Setup Pages
49        id: pages
50        uses: actions/configure-pages@v5
51      - name: Install Node.js dependencies
52        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
53      - name: Build with Hugo
54        env:
55          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
56          HUGO_ENVIRONMENT: production
57          TZ: America/Los_Angeles
58        run: |
59          hugo \
60            --gc \
61            --minify         
62      - name: Upload artifact
63        uses: actions/upload-pages-artifact@v3
64        with:
65          path: ./public
66
67  # Deployment job
68  deploy:
69    environment:
70      name: github-pages
71      url: ${{ steps.deployment.outputs.page_url }}
72    runs-on: ubuntu-latest
73    needs: build
74    steps:
75      - name: Deploy to GitHub Pages
76        id: deployment
77        uses: actions/deploy-pages@v4

After making this change, the website’s CSS loaded correctly, and the site appeared as expected.

Conclusion

If you’re encountering a similar issue with CSS not loading for your Hugo site on GitHub Pages, check the --baseURL parameter in your workflow file. Removing it might resolve the path issues for your static assets. Happy coding!