Hugo on Netlify

Just wanted to share this article about hosting Hugo on Netlify, a static site hosting service (no affiliation – I’m surprised they didn’t come by here to share it in person).


Thanks for the heads-up, this is really cool!

I added it to the press section:

I didn’t hear of Netlify previously. Do people have experience hosting there?

Thanks for sharing!

I’m the author of the blog post and one of the founders of netlify. Really impressed with Hugo and happy to answer any questions about the Hugo on netlify…


Hi @biilmann!

I looked at your blog post and the simplicity of the settings is just amazing. I have a repository at at:

I tried the build after linking up the repo but I get an error message:

Waiting in build queue
8:43:51 PM Fetching cached dependencies
8:43:51 PM No build cache
8:43:51 PM No cached dependencies found. Cloning fresh repo
8:43:50 PM Build started
8:43:53 PM Preparing branch
8:43:54 PM Error preparing repository: exit status 1
8:43:54 PM Error preparing repository: exit status 1

My Netlify settings are the same as the ones in your blog post.

Can you help me out?

Had a look at the build and it seems the checkout of the repository fails because there’s a theme in the repo that git thinks is a submodule without an entry in the .gitmodules file.Here’s the exact error message from our build server:

No submodule mapping found in .gitmodules for path ‘themes/hugo-creative-theme’

I’ve seen this happen a few times before, and think it would probably make sense for our build to just give a warning when this happens…

Thank you very much for your fast reply!

I had a .git file in the theme folder from when I cloned the theme from it’s repository. I deleted this, and pushed everything and the build worked.

Thank you for this excellent service.

PS: +1 on the warning to unknowing users such as myself it is crucial.

Pushed a fix to our buildbot that’ll make it ignore this specific error now :slight_smile:

Hey @biilmann – Loving Hugo support on Netlify, but two issues:

  1. There was a theme I like with Hugo, so I cloned it into our project and added it as a submodule in themes (as per the installation instructions from the theme). Then I wanted to change one thing about it, so I forked it to my own repository, made the change, updated the remote, pushed that commit to my own remote (which was now origin) and updated it in the .gitmodules. It looks like your build script didn’t notice that it was being pointed at a different repository, so the build failed.

  2. How do I get Pygments working with Netlify? Hugo will call out to it during the build process using certain shortcodes, but since it says it’s not found on Netlify’s server then I have to use client-side highlighting.

Thanks again!

Also incredibly easy to use with Bitbucket, more or less same instructions as for Github! Love the combo!

  1. Most likely this is simply a git thing - submodule handling can sometimes be a bit rough. If the submodule is setup correctly, you should be able to just trigger a build from the web UI and mark the “Clear cache” checkbox. This will do a fresh clone…

  2. Pygments is a python dependency, so you’ll want to add a ‘requirements.txt’ file to the root of your repository with the version of pygments that you’re using. For the current version the contents of requirements txt should just be:


That will make netlify install pygments (and cache the dependency) before your hugo build runs…


@biilmann Thanks! Hitting Clear Cache did work. I didn’t realize that you could mix the dependencies like that; it’s so simple it went right over my head :smile: Thanks for netlify (and great support!)

Hi everyone!

I too am very pleased with Netlify so far. I host all my hugo sites with them. It’s incredibly fast, and given how fast Hugo is on the builds, the HugoGithubNetlify arrangement is a match made in heaven! :heart_eyes:

Netlify has also fixed issues I had within minutes, on weekends, sometimes around mid-night despite the fact that I am on their free plan (for now) :slightly_smiling: Here’s 1 of my pawpular production website I have hosted on the HugoGithubNetlify workflow.

I’ve created a detailed screencast. Hope this is useful to everyone, and do let me know if I can improve my screencasts in any way.

Hugo - GitHub - Netlify - Step-by-Step Guide

In this step-by-step video guide, I show you how you can setup your website or blog using Hugo , Github and Netlify.

Table of Contents:

  1. Introduction
  2. Confirm Pre-requisites
  3. Create the local Folder structure
  4. Download and Install Hugo
  5. Configure Hugo
  6. Verify Hugo
  7. Create your Website on localhost
  8. Build the empty website and verify it
  9. Create some Content
  10. Install a Website Theme
  11. Build your Website on Localhost
  12. Build and test your Website
  13. Prepare the Website for Deployment
  14. Initialize your local Git repository
  15. Push your website files to Github
  16. Create and Connect your Website on Netlify
  17. Configure the Custom Domain.
  18. Verify the Custom Domain.
  19. The End

Ha! We just found out about Netlify ourselves, and are in the process of moving from our GH pages/Wercker workflow over there.

Even if you don’t want to use them for your hosting or your main build, the Build Previews thing is amazing (for us especially, since we have a large number of contributors and it’s way easier to merge a PR when you can instantly see what it looks like live).

@mattstratton @Shiva double plus one for Netlify. If you’re working on an open-source project, they’ll provide the pro tier for free, which includes deep git integration…

What does that mean? That means setting up separate dev branches for previewing with stakeholders, etc is as simple as git branch... Then merge it with master, push your changes, and the build is CRAZY quick (much faster than my previous experiences with Wercker (also a great product). It also provides the added benefit of being able to add cache-controls and immediate cache validation. Awesome sauce.

It also provides the added benefit of being able to add cache-controls and immediate cache validation.

@rdwatters I’ve been going crazy trying to find a way to specify the Cache-Control settings for Netlify. Do you have an example netlify.toml that shows how to set the max-age only for certain files (CSS, js, .ico)?

Update: Earlier I had shared a netlify.toml snippet. But it turned out that specifying Cache-Control through that file was buggy/unclear as it could be possible that the [[headers]] TOML table got applied to an unintended Netlify context. But things were messy that way as some Cache-Control headers seemed to apply, and some not.

Using the _header file as I show below, I was able to achieve consistent results:
Put something like below in your hugo site’s static/_headers:

# Paste the below in to test
# Set max-age to 1 year for stuff not expected to update any time soon.
  Cache-Control: public, max-age=31536000

  Cache-Control: public, max-age=31536000

  Cache-Control: public, max-age=31536000

# Favicons
  Cache-Control: public, max-age=31536000
  Cache-Control: public, max-age=31536000
  Cache-Control: public, max-age=31536000
  Cache-Control: public, max-age=31536000
  Cache-Control: public, max-age=31536000
  Cache-Control: public, max-age=31536000

# Also these images used by the refined theme won't be updated frequently.
  Cache-Control: public, max-age=31536000

  Cache-Control: public, max-age=31536000

  Cache-Control: public, max-age=31536000

Howdy folks,

Employee from Netlify’s Support team here and love threads like this! We’re working to improve our own documentation with more examples like these and are thrilled when the community can help each other solve problems :slight_smile:

Just an FYI that we don’t usually monitor this forum or topic, but we do respond to all support requests, so that’s probably a better place to post questions if you want a quick authoritative answer.

In the case of the Cache-Control settings - be careful about following these instructions blindly. We set our caching headers with great intention so you don’t get stuck with stale content after an update and the above examples can break your site for quite awhile (what if your logo changes? sorry - you’re stuck with it for a year since you told me not to refresh favicon.ico :confused: ). Check out this article about how we cache and update content for more information and feel free to ping support if you have follow-up questions, we’re happy to talk you through the best practices.