Build fails with a theme (but not with another one) --> how to troubleshoot?

Using Themes
1

Hi,

I’m trying to change the theme of a Hugo site. With the new theme (theme name: Hextra), building the website fails with lots of (false) errors. With the original theme (theme name: Relearn), the site builds correctly.

With theme “Hextra”

git clone https://gitlab.com/asqatasun/asqatasun-documentation-v6.git
cd asqatasun-documentation-v6
git checkout 7-try-theme-hextra
cd Asqatasun-v6-documentation
hugo server --logLevel debug --disableFastRender -p 1313 --noHTTPCache --verbose

this produces:

Watching for changes in /home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/{archetypes,assets,content,data,i18n,layouts,static}
Watching for config changes in /home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/config/_default, /home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/config/development, /home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/go.mod
Start building sites … 
hugo v0.119.0-b84644c008e0dc2c4b67bd69cccf87a41a03937e+extended linux/amd64 BuildDate=2023-09-24T15:20:17Z VendorInfo=gohugoio

INFO  copy static: syncing static files to /
INFO  build: running step process duration 14.304863ms
INFO  build: running step assemble duration 41.544622ms
ERROR [en] REF_NOT_FOUND: Ref "./Rule-1-10-1": "/home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/content/_index.md:6:7": page not found
ERROR [en] REF_NOT_FOUND: Ref "./Rule-1-10-2": "/home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/content/_index.md:9:37": page not found

(...)

ERROR [en] REF_NOT_FOUND: Ref "./13.Consultation": "/home/mfaure/Documents/Asqatasun/Dossier-0Permanent/0Sources/asqatasun-documentation-v6/Asqatasun-v6-documentation/content/_index.md:26:4": page not found
INFO  build: running step render duration 15.891465108s
INFO  build: running step postProcess duration 13.337µs
Built in 15947 ms
Error: error building site: logged 604 error(s)

With the original theme (Relearn)

git clone https://gitlab.com/asqatasun/asqatasun-documentation-v6.git
cd asqatasun-documentation-v6
cd Asqatasun-v6-documentation
hugo server --logLevel debug --disableFastRender -p 1313 --noHTTPCache --verbose

Site builds without error.

Details

  • Go v1.18.1
  • Hugo v0.119
  • Theme Hextra v0.6.3 used as a go module (not a git submodule)

Question

I’ve looked over the options of hugo command and the Hugo documentation, but couldn’t find help. So how can I troubleshoot this issue ?

2

Have you reached out to the theme author?
https://github.com/imfing/hextra/discussions

3

Thank you @jmooring for the speedlight answer! I’ve filed an issue: Website build fails with Hextra, but doesn't with another theme · Issue #192 · imfing/hextra · GitHub

4

Just out of curiosity: What’s the reason for changing the theme?

5

@McShelby The major pain point is I couldn’t have the navbar working (all entries are always expanded, which is quite unusable as we have normative documents containing lots of categories).

The second reason is just a matter of taste, global design looks lighter.

6

Theme author fixed the issue, Hextra v0.6.5 works well.

Ways to troubleshoot were provided by theme author also.

7

Relearn (theme takes mealy five minutes to clone and is 341MB in size! The culprit is the .git folder which is 310MB! I wouldn’t touch this theme on my projects TBH!)

$ git clone https://github.com/McShelby/hugo-theme-relearn.git
Cloning into 'hugo-theme-relearn'...
remote: Enumerating objects: 452282, done.
remote: Counting objects: 100% (156758/156758), done.
remote: Compressing objects: 100% (53111/53111), done.
remote: Total 452282 (delta 103370), reused 156302 (delta 102970), pack-reused 295524
Receiving objects: 100% (452282/452282), 296.18 MiB | 893.00 KiB/s, done.
Resolving deltas: 100% (275828/275828), done.
Updating files: 100% (541/541), done.

Hextra (just 9MB in size)

$ git clone https://github.com/imfing/hextra.git
Cloning into 'hextra'...
remote: Enumerating objects: 2213, done.
remote: Counting objects: 100% (845/845), done.
remote: Compressing objects: 100% (325/325), done.
remote: Total 2213 (delta 600), reused 692 (delta 506), pack-reused 1368
Receiving objects: 100% (2213/2213), 3.15 MiB | 257.00 KiB/s, done.
Resolving deltas: 100% (1290/1290), done.
8

Thanks @mfaure. That’s interesting, because in the original Learn theme this wasn’t configurable while in my Relearn fork it is (for each subsection if you want to, but defaults to the old Learn style).

1 Like
9

Relearn (theme takes mealy five minutes to clone and is 341MB in size! The culprit is the .git folder which is 310MB! I wouldn’t touch this theme on my projects TBH!)

That’s due to the fact, that the docs are contained in the theme itself with all the screenshots. But it’s really difficult (impossible?) to change the git history in a non-breaking way.

10

What’s the downside of doing that? Maybe clone and archive current to retain history. It’s a great theme.

1 Like
11

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.