What am I doing wrong? My site, built locally with `hugo` looks fine, but there are problems on netlify

Support
, ,
1

I suspect that I must be doing something totally wrong in my usage of netlify.

I have built several websites locally, without any issue, with Hugo (using the hugo command), but when I deploy them, though the build is successful, a number of things are not working.

  1. TOC

Now that Hugo uses goldmark, it is possible to set the number of levels for the table of content.

I have, in my config.toml file:

  [markup.tableOfContents]
    endLevel = 1
    ordered = false
    startLevel = 1

and this works great locally: I only have the first level headers in my TOCs.

But when I deploy on netlify, I see all the TOC levels.

  1. org-mode

org-modeā€™s native support in Hugo through go-org works like a charm locally, but when I deploy on netlify, none of the org code (code block, links, etc.) is rendered (it shows verbatim).

  1. theme using make

One of the themes I use doesnā€™t simply run hugo but a Makefile. While this worked well locally, it did not work on netlify (again, the build was successful, but layout files were not used). I fixed this by removing the Makefile, the theme.toml, the netlify.toml, etc. and having the theme built following a much simpler process.

With all these problems, it seems to me that I must be doing something wrong and I have no idea what.

I first made sure that it was not that I was using different versions of Hugo locally and on netlify by creating a netlify.toml file with:

[build]
  publish = "public"
  command = "hugo"

[context.production.environment]
  HUGO_VERSION = "0.63.2"

This made no difference.

I think that I need a little help here.

Thank you!

  • Here is one of these sites (in a very early draft stage).

  • On this page, which I built from a markdown file, you can see the TOC issue (locally, I only have the 1st levels as I hoped).

  • And on this page, you can see what happens if I use an org-mode file instead of a markdown file (locally, they work as well as as the other): the code block is not rendered, the header with tags and categories has disappeared, etc.).

2

Note: the formatting of the abstract section on the 3rd link should be the same as on the 2nd link (and it is locally).

Also, on the 2nd link, just below the header Useful links, locally, I can simplify my raw html code and skipping all the <p> and </p>: adding blank spaces between paragraph is enough. But apparently, on netlify, I cannot afford that and I need the proper html code. So this is yet another example of how the rendering which works locally by running hugo does not work when I deploy on netlify, even with a netlify.toml file which makes the command specific (hugo) and the Hugo version specific (the same I have locally).

3

Hi @prosoitos, I checked your latest deploy but it does not look like you had a netlify.toml file in your repository. Did you remove it? Could you try setting that env var in your siteā€™s dashboard instead?

4

Yes, I did remove it as it made no difference whatsoever.

[build]
  publish = "public"
  command = "hugo"

[context.production.environment]
  HUGO_VERSION = "0.63.2"

was probably not enough, but I donā€™t know what else I should add in it so that it would actually make a difference.

5

I will have a look into this as this is something I have never done. Thank you for the tip.

7

Your solution worked @Dennis. Thank you!

All the issues I had seemed to have been caused by netlify using a version of Hugo too old for my code.

And setting the Hugo version in the netlify.toml file had no effect (btw, why is that??).

Also: why is netlify not using the lastest version of Hugo by default, unless specified otherwise by the user?? For users who keep their local Hugo up to date, that would solve them the hassle of having to change the environment variable on netlify all the time to make sure that netlify is keeping upā€¦

Or is there a way to set that environment variable in a way that it is always set to the latest version?

8

Note on that last question: I understand that not everyone is on a rolling distro and that the latest Hugo version could break sites for many users.

That said, having to set the Hugo version once (for all those users) is a lot less work than having to keep updating the environment variables on all the sites for users who update Hugo frequently and who keep developing their sites to make sure that netlify is keeping up (unless, again, there is a way to set that environment variable to the latest Hugo, which would be the ideal solution).

9

If setting the Hugo version in the netlify.toml file file was working, I could write a little script to update it each time I update Hugo. But as it is not working, I would love to know whether there is a way to save me from having to poke around on the netlify dashboard every few weeks to update this.

Thanks a lot!!! I appreciate your time and help!!! :slight_smile:

10

Hi, I donā€™t think thereā€™s a way to set ā€˜latestā€™ to get the latest version of Hugo. Most people prefer to have a stable build environment since tracking the latest can mean a breaking change in Hugo can cause your build to fail.

That said, the utility that installs Hugo in our buildbot is open source (GitHub - netlify/binrc: Binrc is a command line application to manage different versions of binaries stored on GitHub releases.). Perhaps you can file a feature request there or even here: GitHub - netlify/build-image: This is the build image used for running automated builds which is the build-image our buildbots use.

11

OK. I will explore those. Thanks again for the help @Dennis :slight_smile:

12

Hi @prosoitos - in case it helps, this is the contents of my netlify.toml file, which I use to set the Hugo version, itā€™s slightly different than the one you posted:

[build.environment]
  HUGO_ENV = "production"
  HUGO_VERSION = "0.64.0"

I use a simple shell script to update the version number every time a new Hugo release comes out, after I test locally that everything still works: zzamboni.org/update-hugo.elv at master Ā· zzamboni/zzamboni.org Ā· GitHub (this is written in Elvish, which is the shell I use, hopefully the idea is clear and easy to replicate in other shells).

1 Like
13

Ah cool! I will see if this format in a netlify.toml works for my site. The format I was using might have been outdated and that might have been the problem.

Once I have a working netlify.toml file, writing a script is not a problem (btw, I had never heard of Elvish. It sounds like an interesting project!! I personally use zsh).

Thanks!!

14

This netlify.toml file format works. Thank you @zzamboni for your help with this! Being able to set the Hugo version without having to manually do it on the netlify site will make things a lot easier.

The format I was using is the one used by the Hugo theme I am using on one of my sites. I am not sure whether it is working for others using that code or not, but I might open on issue on that. That is also the format that Hugo is suggesting.

I am not sure where the best place to find documentation on that file really is. The Hugo/netlify integration seems to be lacking some documentation on both the Hugo and the netlify sides.

15

Maybe a lot of people think that they have set Hugo to a specific version, but they have not and are just using the default. As long as their build and site arenā€™t broken, they may not realize if their netlify.toml is not doing anything.

16

just to make sure i understand, @prosoitos - are you saying our docs arenā€™t quite correct on this? If yes, we should definitely do a review.

17

The format I used was not working for me while the format given by @zzamboni works.

That said, there might be subtleties I am not aware of which caused the format I initial used not to work. Maybe, in order to set the Hugo version with that format, other things need to be done that I was not doing.

So I could be wrong. But with my naive eyes, it looks like that format does not work and the one suggested by @zzamboni works perfectly (without changing anything else in my site).

So yes, it might be worth looking into it.

18

I was also struggling to find much documentation on how to set that file.

The Hugo site states:

The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this siteā€™s netlify.toml

and then there is an example without any explanation.

I used it as a template for my file which had no effect. But again, that format might work if used in conjunction with other things I was not doing.

There may be more information on this in the netlify docs, but I did not find it.

19

great, thanks for summarizing that. Iā€™ll ask our docs team to take a look!

22

Great! Thanks for looking into this!

23

Hi @prosoitos, since Hugo is an open source project, their docs are open source, too! If theyā€™re not giving you the correct information, you can submit an issue or click the ā€œImprove this pageā€ button at the bottom of any other their docs pages to suggest an improvement.

In the Netlify docs, we avoid overly detailed instructions for other tools, because they can change without our knowledge. We do include some brief tips for Hugo in our Common configurations doc, as well as more generally applicable instructions for Environment variables and the netlify.toml file.