Getting Started With Hugo

I recently switched my site from WordPress to Hugo, a static site generator. I decided to leave WordPress for a few reasons: I don’t need many of its features, the security worries, and the slower page loads that come with it. While Hugo doesn’t provide a nice GUI CMS front end like WordPress, it fairly easy to navigate, and your pages and posts are written in Markdown and converted to a set of HTML pages and accompanying static files automatically. Read on for a guide to getting started with Hugo.

Installing Hugo

I am going to assume for this tutorial that you are running a Linux distribution that supports the snap package format. The benefit of using the snap is that you can make sure you have the latest version of Hugo, regardless of what’s available in your distro’s repos. Note that Hugo should be installed on the machine you will use for web development. Do not install it on your web server. To install, simply type:

snap install hugo

For installation instructions for other distros or OSes, see the Hugo installation docs.

Using Hugo

Getting started with Hugo is pretty straightforward. Just take the following steps.

Don’t RTM

The Hugo docs are great, but the best way to get started is to make a site. Othwerise, you may find yourself quickly overwhelmed with a lot of information that you may not need. So first things first, skip the docs, for now.

Create Your First Hugo site

To start developing your site, open a terminal and type the following commands:

mkdir <yourSiteDirectory>
cd <yourSiteDirectory>
hugo new site .
Find and Install A Theme

Head over to the Hugo themes page and find a theme that will meet your needs. If you can’t find the perfect theme, but you know a bit of HTML/CSS, pick the one that is closest to what you want and know that you can edit it. If you want to edit a theme and you have a github account and want to easily keep your changes while taking advantages of updates from the theme’s creator, read this first.

Now that you have found a theme, return to your terminal window and make sure your are still in <yourSiteDirectory>. Then change to the themes directory and type the correct url for installation. The following example uses this site’s theme:

cd themes
git clone https://github.com/bickhaus/hugo-dusk.git

NOTE: If you do not have git installed, you will need to install it to perform the above tasks (e.g., sudo apt install git).

Customize Your Site and Create Content

Let’s start personalizing your site. The nice thing about using a theme is that it contains a directory called exampleSite. The example site will give you an idea of how to organize in order to take advantage of your theme’s features and get up and running. Spend a couple minutes checking it out, and then take the following steps.

  1. Setup the config.toml file which is stored in <yourSiteDirectory>. Here we will leverage the afformentioned exampleSite by using it’s config file as it contains theme specific parameters. The simplest way to do this is to open the terminal and:

    cp <pathToExampleSite>/config.toml <pathToYourSiteDirectory>

Now you can open the file in the text editor of your choice to customize it.

  1. Familiarize yourself with “front matter.” Each page and post have front matter at the top of the file which specifies things like title, author, tags. Refer to the pages and posts in your theme’s example site to see front matter in action. To use the default front matter provided by your theme each time you create a post from the command line, copy the theme archetypes to your site’s archetypes directory:

    cp <yourSiteDirector>/themes/<yourTheme>/archetypes/* <yourSiteDirectory>/archetypes

If you have other front matter or particular markdown that you want in every post, consider adding that to the default file in your site’s archetypes directory. You could also create a new archetype.

  1. Add content to your site. Pages and posts for your site are stored as individual markdown files (.md extension). While you can simply create a file in a text editor and start writing, it won’t leverage the archetypes (that can prepopulate front matter, etc.) we tweaked in the previous step. For this reason, it’s better to use hugo to create files for your site.

    cd <yourSiteDirectory>

# For new pages
hugo new filename.md

# For new posts
# Replace posts w/ post, if necessary (refer to example site)
hugo new posts/filename.md

Now you can open the file in a text editor to add content.

Here are a few other things to keep in mind:

  • You only need to add text/multimedia to each file as the theme will create the appropriate header/footer, etc.
  • Filenames become the links on your site and the title of the page/post. E.g.,
    • about.md:
      • link: yourDomain.com/about
      • title: “About”
    • post/first-post.md:
      • link: yourDomain.com/post/first-post
      • title: “First Post”
  • Your theme’s front matter may default to including draft: true. Prior to building your site (detailed below), you will need to remove this designation for all pages and posts that you are ready to make public.
  • If you are migrating from a CMS like WordPress, you can automate (part of) the process. Click here to learn more.
Viewing Your site

You can get a glimpse of how your site will appear anytime by running the following command while in <yourSiteDirectory>:

hugo server

Then open a web browser and type http://127.0.0.1:1313. If you look at the site and decide to make some changes, you can leave this page open. Any time you make a change to your site while hugo server is running, your site will automatically rebuild itself.

Building the Site

When your site is ready for public consumption, navigate to <yourSiteDirectory> in the terminal and type:

hugo

If you ls <yourSiteDirectory> now you will see a new directory called public. This directory contains everything that needs to be uploaded to your web server. Copy its contents to the correct directory on the server, and you are finished!

Final Step: RTM (optional)

Now that you are familiar with Hugo and how easy it can make building a site, check out the documentation. Get a better idea of the directory structure of your site here. Check out a comprehensive list of configuration settings, learn more about archetypes, or whatever topic you want to more know about. There is a lot cool stuff to check out, and you may find ways to further customize and streamline your workflow.

Appendices

Regarding Custom Themes

If you are planning to tweak a theme, don’t just download it to your site’s directory and start making changes. If you download a new version of theme at some point, you will lose your changes and have to reimplement them. Instead, fork the theme on GitHub first. You can do this by making sure you are logged into GitHub and then clicking the Fork button at the top of your desired theme’s page. This will create a copy of the repo in your own GitHub profile. Now you can open a terminal and do the following:

mkdir <placeToStoreYourDevelopmentCopyOfTheTheme>
git clone <urlToYourForkedTheme>

Now make the changes that you want, and remember to git commit -am 'note re: changes' as you go. When you are finished, you can git push origin master so that the changes will be saved in your repo on GitHub. Now, if the theme you forked is updated, you can merge those changes into your version without losing your work! Return to the tutorial.

Migrating From Another Platform

There are a handful of platforms for which there are automated tools for migration. You can find more information here. I used the wordpress-to-hugo-exporter. To use it click the green Clone or download button and then click Download ZIP. Then pull up the admin interface for your WordPress install, and upload the plugin (still zipped). It should install automatically. You should now see “export to Hugo” in the menu with the other import/export options. Click that and you will now have a hugo-export.zip file which will contain markdown files representing all of the pages and posts for your current site, as well as, a config file.

This tool is awesome, but it’s not perfect. Expect to read through every page and post to make sure that they are properly formatted. If your site is a tech blog that includes code of some sort, this is a good time to look into whether your theme supports syntax highlighting and decide whether you want to take advantage of it, as you may need to add the proper markdown to do so. Return to the tutorial.

comments powered by Disqus