butiran-✗

med hugo css consistency minify

· 4 mins read

info

content

Photo by Richard Dykes on Unsplash

It has been a while since I have encountered the problem. It is the apprearance of the pages, which are different between rendered locally and remotely on GitHub Pages. There is a long and exhausted dicussion about it due to misprompting and perhaps misanswers (GPT-5, 2025). It might be considered as a misleading dicussion 🤣.

Unexpected appearances

Following are the unexpected apprearances of the landing page of my website, local and remote.

Press enter or click to view image in full size

Press enter or click to view image in full size

Rendered landing pages with Hugo on local server (top) and on GitHub Pages (bottom).

Press enter or click to view image in full size

Press enter or click to view image in full size

A rendered post with Hugo on local server (top) and on GitHub Pages (bottom).

The two previous figures show that rendered pages on local server have narower space compared to the ones on remote server. At that time I was thinking about the default style that is uncontrollable using the provided CSS.

Inconsistent builds

Unnoticeable, hugo serves and build the site with different flag. On local server I use following command

$ hugo server -D

while in the hugo.yml for GitHub Actions there are following lines

      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
        run: |
            REPO_NAME="butiran"
            BASE_URL="https://${{ github.repository_owner }}.github.io/${REPO_NAME}/"
            hugo --minify --baseURL "$BASE_URL"

showing that one does not use --minify flag, while the other not.

Solution

Actually, there two options. The first is dropping the use of the flag in hugo.yml for consistency with the local server. And the second is use the flag in local server and local deployment. The local deployment is another way to produce the output (HTML, CSS, JS, and other files) for further debugging.

The second is chosen since minified HTML pages will increase downloading times as it reduces web-page sizes and also accelerate parsing times (Canina, 2018), which is achived by removing unnecessary or redundant data from an HTML file without affecting its functionality, e.g. removing white space, comments, and shortening variable and function names (Lilliu, 2023).

The lines in hugo.yml for GitHub Actions are still the same, but the way to serve it locally becomes

$ hugo server -D --minify

and to build it

$ hugo -d public/butiran --baseURL "/butiran" --minify
Start building sites …
hugo v0.146.4-985af1c097fd6a7830ba1ab307dc0d959663e344+extended windows/amd64 BuildDate=2025-04-14T13:10:30Z VendorInfo=gohugoio


                   |  EN
-------------------+-------
  Pages            | 1790
  Paginator pages  |   50
  Non-page files   |    0
  Static files     |   79
  Processed images |    0
  Aliases          |    1
  Cleaned          |    0

Total in 8191 ms

where the produced output can be served using (Zaczyński, 2023)

$ py -m http.server -d public
Serving HTTP on :: port 8000 (http://[::]:8000/) ...
::1 - - [12/Oct/2025 16:41:20] "GET /butiran/ HTTP/1.1" 304 -
::1 - - [12/Oct/2025 16:41:20] "GET /butiran/css/main.min.5d949e138e137f26bbbc6fbe151c3e39ca49a674bd5c6f0f3a9ff79176ee1043.css HTTP/1.1" 304 -
::1 - - [12/Oct/2025 16:41:20] "GET /butiran/js/main.23cd0c7d837263b9eaeb96ee2d9ccfa2969daa3fa00fa1c1fe8701a9b87251a1.js HTTP/1.1" 304 -

where the generated files are stored in public/butiran. Now, there are three output to compared as in following section.

Results

Following are the results from build locally and served using Python module http.server, served with Hugo, and on GitHub Pages.

Press enter or click to view image in full size

Press enter or click to view image in full size

Press enter or click to view image in full size

Consistent apprearances of a landing page.

It seems that all three outputs have consistent appearances. Let us also see the other page mentioned earlier.

Press enter or click to view image in full size

Press enter or click to view image in full size

Press enter or click to view image in full size

Consistent apprearances of a post page.

It seems that all three pages showing consistent appearances.

Possible explanation

I am not sure there it will be the cause, but perhaps stripping the white space could lead to the change of layout to two adjacent div elements if the CSS is not carefully designed. Until now, it is the only explanation that I can come up with.

Summaries

After reading the story you are able to

  • use Hugo –minify flag to produced consistent CSS results,
  • know where might be the source of inconsistent results,
  • plan to mitigate such problem in the future.

Refs