Hugo Quick Start

Quick Start

Create a Hugo site with the beautiful Ananke theme.

This Quick Start guide is for macOS. For installing Hugo on other operating systems, please see this link。

It is recommended that you have Git installed on your computer when running the code in this Quick Start.

For other ways to learn Hugo, such as books or video tutorials, please see this link。

Step 1: Install Hugo

Homebrew and MacPorts are two package managers for macOS, which can be installed via brew.sh and macports.org. If you are using a different operating system like Windows, please see this link。

brew install hugo
# or
port install hugo

To verify that Hugo is correctly installed, enter the following command:

hugo version

Step 2: Create a New Site

hugo new site quickstart

The command above creates a new folder named quickstart and generates the new site within it.

The default configuration file type for Hugo is TOML. If you want to use the YAML format for your configuration file, add the “–config-format” parameter when generating the new site:

hugo new site quickstart --config-format yaml

Step 3: Add a Theme

The link themes.gohugo.io is the list of available Hugo themes. This Quick Start uses the Ananke theme.

First, download the theme from GitHub and add it to the “themes” folder:

cd quickstart
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

If you do not have a GitHub account:

  • If you do not have Git installed, you can directly download the latest version of the theme archive from https://github.com/budparr/gohugo-theme-ananke/archive/master.zip.
  • Then, unzip the .zip file, which will create a folder named “gohugo-theme-ananke-master”.
  • Rename the folder to “ananke” and copy it into the “themes” folder.

Finally, write the theme name into the site configuration file:

echo 'theme = "ananke"' >> config.toml

Step 4: Add Some Content

You can manually create content files (e.g., content//.) and add some front matter (metadata) at the beginning of the file. However, a better method is to use the new command to automatically complete the above (e.g., adding a title and creation date):

hugo new posts/my-first-post.md

If needed, you can edit this newly generated content file. Its beginning content will look similar to this:

---
title: "My First Post"
date: 2019-03-26T08:47:11+01:00
draft: true
---

Draft specifies whether the current file is a draft. If it is true, the file is in draft status and will not be deployed to the site for display. Once you have finished the final editing of the file, you can set draft: false. For more information, see this link。

Step 5: Start the Hugo Server

Now, start the Hugo server and specify that draft files should also be deployed and displayed:

hugo server -D

You will see output similar to the following:

                   | EN
+------------------+----+
  Pages            | 10
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  3
  Processed images |  0
  Aliases          |  1
  Sitemaps         |  1
  Cleaned          |  0

Total in 11 ms
Watching for changes in /Users/bep/quickstart/{content,data,layouts,static,themes}
Watching for config changes in /Users/bep/quickstart/config.toml
Environment: "development"
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 127.0.0.1)
Press Ctrl+C to stop

Access your new site via http://localhost:1313/.

You can try modifying the content files and refreshing your browser to see the changes (sometimes you need to force a refresh of the browser, typically with the shortcut Ctrl-R).

Step 6: Customize the Theme

Your new site already looks great, but you might want to make a few small modifications before pushing it live to the public.

Site Configuration

Open the config.toml file with a text editor:

baseURL = "https://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "ananke"

Try changing the “title” information above to be more personalized. Additionally, if you already have a domain name, you can set it in the “baseURL” property. Note that when starting Hugo in development mode locally with “hugo server -D”, you do not need to set this value.

Tip: Any modifications to the site configuration file or content files while Hugo is running will be immediately displayed in the browser. The only thing you need to do is refresh the browser, sometimes requiring you to clear the cache.

For other configuration options for the Ananke theme, please refer to the theme website.

For more in-depth theme customization, please see this link.

Step 7: Build Static Pages

It’s simple, just input:

hugo -D

By default, the static pages will be generated in the ./public/ folder (you can temporarily change the output path with the -d/–destination parameter when executing the command, or modify it permanently via the publishdir property in the site configuration file).