Getting started with Hugo

Posted on June 5, 2019 | 6 minute read

Hugo is an open source static site generator written in Go which also claims to be the fastest framework for building websites. With Hugo you can write your posts in the markdown markup language and most configuration happens inside a toml file. It’s simple to setup with just a couple of steps needed and can be configured to match your wishes. So let’s give it a go :)

Installation

Hugo is commonly included by package managers - which I personally prefer to use - but can also be installed via the repository.

Assuming you have a working Go installation you can simply run following commands and let the magic happen:

go get -v -u github.com/gohugoio/hugo
cd $GOPATH/src/github.com/gohugoio/hugo
go install -v

After this Hugo should be installed on your system.

which hugo
/home/penguwin/code/golang/bin/hugo

Now after we’ve installed the software we can start creating a new blog and configure it’s contents.

Creating the blog

At first head into the folder where you locally want to store your blog with it’s files. There you can run following command to let hugo create a sites skeleton with your desired name.

hugo new site pengublog

Following message should be printed out after creation:

Congratulations! Your new Hugo site is created in /home/penguwin/pengublog.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/, or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Now we have the basic structure for your site but we still need to tweak it a little bit more. As we can see in the upper message we still need to add a Theme and some content.

Choosing a theme

There’s a wide variety of free and open source themes which can be used for your blog. For this example I’ve choosen a clean and simple theme called finite from the Hugo themes showcase.

Themes are added as git submodule. Head into your newly created folder and hit following:

git init
git submodule add https://github.com/lambdafu/hugo-finite themes/finite
Initialized empty Git repository in /home/penguwin/pengublog/.git/

You’ll now be able to find the designs in the /themes folder. To actually use it with Hugo you still need to declare it in your config.toml file.

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

Writing blog posts

In order two have a nice blog, you need to add some content. With hugo creating a post is also quite easy:

hugo new post/my-first-post.md
/home/penguwin/pengublog/content/posts/my-first-post.md created

Now you can edit the markdown files content laying in content/post/ as you desire.

Starting the hugo server

Now we finally want to see our blog in action. To start the server with drafts enabled you’ll need following command:

hugo server -D

If everything works out a message like this should be printed out.

Building sites …
                   | EN
+------------------|-----+
  Pages            |   9
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 111
  Processed images |   0
  Aliases          |   1
  Sitemaps         |   1
  Cleaned          |   0

Total in 26 ms
Watching for changes in /home/penguwin/pengublog/{content,data,layouts,static,themes}
Watching for config changes in /home/penguwin/pengublog/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

As we can see the server waits at your localhost and will live-reload as soon as you edit the content of the blogs configs or markdown posts.

Conclusion

Getting started with Hugo is super easy and you can create a nice blog from zero to ready-to-go in just a couple of commands. There’s still some work needed in order to publicate the blog into the wild internet and of course we still have to personalize the blog with posts and information about the author before we deploy it online. For these further steps I can recommend reading the docs online as Hugo is well documented and actively developed by a nice community.

References

Hugo environment

This is how my hugo environment looks like after installation:

hugo env
Hugo Static Site Generator v0.55.6/extended linux/amd64 BuildDate: unknown
GOOS="linux"
GOARCH="amd64"
GOVERSION="go1.12.4"

Hugo help message

Here’s the help text for hugo:

hugo version
hugo --help
Hugo Static Site Generator v0.55.6/extended linux/amd64 BuildDate: unknown
hugo is the main command, used to build your Hugo site.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at http://gohugo.io/.

Usage:
  hugo [flags]
  hugo [command]

Available Commands:
  config      Print the site configuration
  convert     Convert your content to different formats
  env         Print Hugo version and environment info
  gen         A collection of several useful generators.
  help        Help about any command
  import      Import your site from others.
  list        Listing out various types of content
  new         Create new content for your site
  server      A high performance webserver
  version     Print the version number of Hugo

Flags:
  -b, --baseURL string         hostname (and path) to the root, e.g. http://spf13.com/
  -D, --buildDrafts            include content marked as draft
  -E, --buildExpired           include expired content
  -F, --buildFuture            include content with publishdate in the future
      --cacheDir string        filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
      --cleanDestinationDir    remove files from destination not found in static directories
      --config string          config file (default is path/config.yaml|json|toml)
      --configDir string       config dir (default "config")
  -c, --contentDir string      filesystem path to content directory
      --debug                  debug output
  -d, --destination string     filesystem path to write files to
      --disableKinds strings   disable different kind of pages (home, RSS etc.)
      --enableGitInfo          add Git revision, date and author info to the pages
  -e, --environment string     build environment
      --forceSyncStatic        copy all files when static is changed.
      --gc                     enable to run some cleanup tasks (remove unused cache files) after the build
  -h, --help                   help for hugo
      --i18n-warnings          print missing translations
      --ignoreCache            ignores the cache directory
  -l, --layoutDir string       filesystem path to layout directory
      --log                    enable Logging
      --logFile string         log File path (if set, logging enabled automatically)
      --minify                 minify any supported output format (HTML, XML etc.)
      --noChmod                don't sync permission mode of files
      --noTimes                don't sync modification time of files
      --path-warnings          print warnings on duplicate target paths etc.
      --quiet                  build in quiet mode
      --renderToMemory         render to memory (only useful for benchmark testing)
  -s, --source string          filesystem path to read files relative from
      --templateMetrics        display metrics about template executions
      --templateMetricsHints   calculate some improvement hints when combined with --templateMetrics
  -t, --theme strings          themes to use (located in /themes/THEMENAME/)
      --themesDir string       filesystem path to themes directory
      --trace file             write trace to file (not useful in general)
  -v, --verbose                verbose output
      --verboseLog             verbose logging
  -w, --watch                  watch filesystem for changes and recreate as needed

Additional help topics:
  hugo check   Contains some verification checks

Use "hugo [command] --help" for more information about a command.

Share via

Tags:blog go hugo