Set Up Hugo with Go

Screenshot using Gravatar theme

To build Hugo sites locally, install Homebrew and Hugo. You do not need to install Go to use Hugo as your static site generator. These instructions are for a Mac or Linux system, but you can also read the Windows installation instructions on the site.

Since Hugo is built on Go, you can use the binary for your operating system. No need to maintain a development environment. Upgrades are easy too, get a new binary and install it and you’re upgraded.


  • Windows, MacOS, or a Linux-based environment.
  • On MacOS, you will install Homebrew.
  • On Windows, you must install Docker.
  • On Windows, you must install Git for Windows which includes Git Bash.

Set up Hugo on Windows with Git Bash and Docker

You can also set up Docker and then use this Docker image to install Hugo. With the Docker image, you set up alias commands for hugo running in Docker, but can work in Git Bash and follow this tutorial using the same hugo commands in Git Bash on Windows.

Set up Hugo on MacOS

  1. Install Homebrew. See the Homebrew site for instructions.
  2. Use Homebrew to install Hugo.

    $ brew install hugo
  3. Verify the hugo installation by checking the version value.

    $ hugo version
    Hugo Static Site Generator v0.74.3/extended darwin/amd64 BuildDate: unknown

Starting a Hugo site

For a Hugo static site, you can choose your specific theme after you create the source files. The theme we’ll use in this tutorial is hugo-theme-learn. To start a new site in the current folder, run:

   $ hugo new site docs-as-code
   $ cd docs-as-code
  1. Take a look at the files created in the directory with an ls command:
      $ ls -A
      archetypes	content		layouts		themes
      config.toml	data		static
  2. Initialize the current directory as a Git repository, which will enable you to bring the theme in as a Git submodule.
    $ git init
    Initialized empty Git repository in /Users/annegentle/src/src/hugo-example/.git/
  3. Edit config.toml in any text editor you like to get started. Choose a title for your site and the theme, in our case, hugo-theme-learn. The theme name in your configuration file must match the name of the specific theme directory inside the /themes directory, so we will add those files in the next step.
      baseURL = ""
      languageCode = "en-us"
      title = "Learning Hugo Site"
      theme = "hugo-theme-learn"
  4. To get the theme files in the /themes directory, and keep them updated, use a git submodules command to get the required theme files as well as keep them updated.
      $ git submodule add themes/hugo-theme-learn
  5. For Hugo, the content folder contains the site source content. For your home page, make an document in the content folder and write it with Markdown content. Switch back up one level since you just cloned the theme files.
      $ cd ..
      $ hugo new
  6. Next, add a new page using the hugo command, hugo new:
      $ hugo new
      /Users/agentle/src/hugo-example/doc-machine/content/ created
  7. You can keep adding files with the hugo new command so that the Markdown files are pre-populated with the front matter:
      title: "Prerequisites"
      date: 2018-06-16T10:38:19-05:00
      draft: true

Build a Hugo site locally

Once you’ve prepared your local system, you can build locally and review the site in your browser.

For Hugo, it’s important to know that draft pages are only served when using the -D parameter.

  1. Run the hugo server command with the -D parameter (to serve draft pages).

    $ hugo server -D
                          | EN
         Pages            | 12
         Paginator pages  |  0
         Non-page files   |  0
         Static files     | 67
         Processed images |  0
         Aliases          |  0
         Sitemaps         |  1
         Cleaned          |  0
       Total in 48 ms
       Watching for changes in /Users/agentle/src/hugo-example/doc-machine/{content,data,layouts,static,themes}
       Watching for config changes in /Users/agentle/src/hugo-example/doc-machine/config.toml
       Serving pages from memory
       Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
       Web Server is available at http://localhost:1313/ (bind address
       Press Ctrl+C to stop
  2. Open the Web Server URL, http://localhost:1313/ in your local browser to view the site. (By default, the theme may be purple instead of green.) Example Hugo site
  3. Press Ctrl+C in the server terminal to stop the Hugo server.
  4. You can add your files to a Git commit. Refer to Working with content in GitHub repositories for a documentation workflow with your Hugo site.

Modify the Hugo theme

By default, the Hugo Theme “Learn” has a purple sidebar. How about changing the color and logo displayed in the sidebar? Here’s how. While we’re at it, let’s make sure to configure the search tool that works best with this theme.

  1. Edit the config.toml file and add these lines to the config.toml file. This example shows setting the themeVariant to green.
    themeVariant = "green"
  2. You can make sure that the theme works with the lunr.js JavaScript search engine by adding these lines to the config.toml file.
    home = [ "HTML", "RSS", "JSON"]

What’s next

Evaluating options

Additional references