How to save time when serving your Hugo site locally on a Mac

Bringing up my Hugo site locally is now a breeze instead of a chore.

Ron Erdos • Updated March 20, 2020
Tested with Hugo version 0.74.3

Why I wrote this tutorial

I’m a big believer in saving time.

I’m a big believer in reducing steps in processes you do often.

Here’s how to do that when serving your Hugo site locally.

My old workflow to run Hugo locally

Here are all the steps I used to take to get my Hugo site running locally in my browser:

  1. Open Terminal (the Mac’s native command line interface, or CLI for short)

  2. Navigate to the folder where I store my repos (/Users/ron/Projects), using Terminal’s “change directory” command (cd) to do so, like this: cd Projects.

  3. Navigate to the Projects subfolder where this Hugo site is stored (cd MoonBooth)

  4. Run hugo server to spin up a local instance of this Hugo site

  5. Select and copy the address Terminal gives me which tells me where my Hugo site is running locally (e.g. http://localhost:1313/)

  6. Open a new tab in Chrome

  7. Paste in that localhost address, and, finally, I’m able to view my site running locally in Chrome.

That’s a lot of steps, right?

My current workflow to run Hugo locally

And here’s what I do now instead:

  1. First, I open the terminal inside VS Code , the free Microsoft code editor I highly recommend. More on VS Code later.
  2. Next, I type in just two letters, mb (which stands for MoonBooth, this site’s name), into the terminal integrated within VS Code, and hit return.
  3. Finally, I command-click on the url (e.g. http://localhost:1313/). I’m automatically taken to my default browser, Edge , where I see my local Hugo site running.

Way quicker, right? And all from within VS Code, the editor I usually have open anyway.

I’ll show you how to do this in a minute. But first, if you don’t know what an “alias” is on your Mac, take a minute to read the below, as you’ll need this knowledge to replicate my speedy setup.

Part A: How to create an alias on your Mac to quickly serve your local Hugo site

If you’re not sure what an “alias” is, check out the explainer box just above.

Here are the steps:

1. Open Terminal

Open Terminal, or a CLI of your choice (iTerm, VS Code etc). I’ll refer to the Mac’s native Terminal app to keep things simple.

2. Open a special file on your Mac where aliases go

Aliases go in a certain file on the Mac, and that file is ~/.bashrc.

The filename can look quite alien for first-time users, but this whole process is actually quite straightforward once you get the hang of it. I promise!

If you have VS Code, the easiest way to open this file is by entering this command into Terminal:

code ~/.bashrc

That will open the file you need in VS Code.

If you don’t have VS Code, you could enter this command instead:

open -a TextEdit ~/.bashrc

This will open the file you need in TextEdit, a simple text editor that comes pre-installed on your Mac.

3. Add your alias to the file

Now you’ll need to enter a line of text and save the file. Don’t just copy and paste the line below—you’ll need to change it first.

alias mb="cd /Users/ron/Projects/MoonBooth && hugo server"

Let’s walk through this line.

alias tells my Mac that I want to create a new alias.

mb is the name I gave my new alias. I picked something super short (two letters) that’s easy to remember (mb stands for “MoonBooth”, the name of this site). Obviously you should pick something that makes sense for you.

= means everything that comes next will be assigned to my new mb alias. Make sure you don’t have a space on either side of the equals sign, as this may cause errors.

" (quote marks) are needed so that my Mac can interpret my instructions.

cd stands for “change directory”. The next bit (below) is the directory itself.

/Users/ron/Projects/MoonBooth is the directory on my Mac where I keep my Hugo repo for this site (MoonBooth). You’ll obviously need to enter the location of your Hugo site on your Mac. Only the /Users/ part will be the same, the rest will be different.

&& means we are starting another command, which will be executed as soon as the first one is finished.

hugo server tells Hugo to serve the site locally.

" (quote marks) are needed to close off the quote marks we opened up earlier.

4. Save and close the file

You won’t need to edit it any more.

5. Force your Mac to notice your new alias

We need to tell your Mac about your new alias.

To do this, enter this command into Terminal and hit return:

source ~/.bashrc

Now you’re good to go!

If your Hugo site’s not already running locally, enter your new alias into Terminal and hit return.

Again, my alias for this site, MoonBooth, is mb, but yours will be whatever you named it in the steps above.

Hopefully you named it something short, because you’ll be typing it a lot!

Don’t worry if you want to shorten it—you can do this by repeating the above steps, but this time, editing the existing alias name rather than creating a new one.

Now let’s move on to the final optimisation step. It’s optional, but worth it.

Part B: How to visit your local Hugo site in your browser more quickly with VS Code

OK, so after entering your alias (such as mb) into Terminal, your Hugo site will be running locally, but you won’t be able to see it until you visit the address Hugo gives you.

You can find the address in the Terminal output. The relevant line looks like this:

Web Server is available at http://localhost:1313/

The optimisation step here is simply to switch from the Mac’s default Terminal to a better alternative.

The reason to switch is because if you’re using Terminal, you’ll have to copy that address, open up a new browser tab, and paste it in.

However, when you use a different application (such as VS Code or iTerm), you don’t have to copy and paste that localhost address. You can simply command-click—hold down Command () and click with the mouse at the same time—to be taken directly to your local Hugo site in your default browser (such as Firefox, Chrome etc).

It may not sound like much of an optimisation, but when you’re starting your Hugo server numerous times a week, it’s well worth it.

How to download VS Code (a free Microsoft code editor)

You can download the excellent VS Code here. As mentioned above, VS Code can be used to edit your Hugo files and compose blog posts and serve your Hugo site locally.

It’s quite nice to have everything you need to manage your site—content updates, code edits, previewing and publishing—all in the one app.

"Thanks so much for your work ... I'm migrating my WordPress blog to Hugo and it's been really helpful" — Francisco S., engineer and blogger

The planets in our solar system