last updated: 29 August 2018 (approximate reading time: 6 minutes; 1093 words)
Hugo uses a command-line interface. This means you need to type text to make things happen. There’s no graphical interface to click with a mouse.
While the command line is scary—and to be frank, fairly icky—it does bring some flexibility. However, to use the program, you need to get familiar with the commands that Hugo will understand, so here are some of the basics to get up-and-running.
Instead of remembering commands, I use batch files to run Hugo.
Batch files are plain text files but with the suffix changed from txt to bat. Instead of typing the command into the command line, the command is written in the batch file. To execute the command, the batch file can then be clicked (or double-clicked if you’re a double-clicker).
Batch files are a Windows thing…if you’re on Unix or a Mac, then you may be able to do something similar with shell scripts.
For me, one of the most useful features of Hugo is the local server. This runs a live copy of a website on a local machine (in other words, there’s no need for an internet connection—you just use the computer in front of you).
As you might expect, this functionality is really useful while building and editing websites. It’s especially useful since its output is live—in other words, any changes to the text or tweaks to the theme controlling the layout of the website will be shown in real time.
To run the local server type the command
hugo server at the command line (or set a batch file). You can then view the website running on that server by opening a web browser (any web browser) and going to http://localhost:1313/.
Generate the Site
When you have built your site in Hugo, you can upload it to your webhost.
hugo invokes the generate command; your website will be created in the /public folder of your local Hugo install. Upload the (entire) contents of this folder to your webhost and your site will be visible to the world. If you make a change to your site, you need to regenerate the site using the same command (and the updated site will then need to be uploaded).
If there is any content in the /public folder when you run
hugo (for instance, there is an older version from when you last generated your site), then it will be overwritten when the command is re-run.
Document Level Settings
Let’s move away from the command line for a moment and look at documents—and in particular, the front matter for documents (in other words, the data at the top of each markdown document).
We can use the command line to control what we see based on two items in the front matter.
Any document in Hugo can be set as a draft. Draft documents will not be published (in other words, they will not be generated when the site is regenerated) and they do not show when the local server is running.
To set a document as a draft, in the front matter add a tag:
draft = "true" (I’m using the TOML format for front matter).
To mark a document as ready to publish, you can set the tag to:
draft = "false" or simply delete the tag.
As a matter of preference, I keep the tag (but marked false, rather than simply deleting it when I’m ready to publish) because it provides a fast and convenient way to unpublish a specific document (I simply change
draft = "false" to
draft = "true" and regenerate/republish the site).
Each document has a date listed in the front matter using the format:
date = "yyyy-mm-dd" (again, I’m using the TOML format).
Dates can be set in the past or in the future.
Documents can also be set with expiry dates:
expiryDate = "yyyy-mm-dd".
When a site is regenerated, any document with an expiry date which has passed will not be included in the site. This flag has great utility if you want to ensure that old material is automatically cleared out.
Automatic Publishing and Removal
If you are using a server to automate the publishing and removal of documents, then setting the date and the expiry date will help you ensure any documents automatically go live or are automatically removed at the appropriate time.
You can add flags to control how a command is executed.
For example, the command
hugo --cleanDestinationDir will generate the site and will clean the destination directory.
Seeing Drafts: Flags
By default, draft documents do not show. But you may want to see your drafts while you are working on your local server. By adding a flag to the command we can tell Hugo to display the site with drafts visible, thus:
hugo server --buildDrafts
This command will display drafts as if they had been published (as well as the material that has been marked for publication).
This flag also works with site (re)generation:
Seeing Into the Future: Flags
By default, Hugo generates and shows on the local server documents dated today and before. In other words, it does not publish documents with dates set in the future.
But as with drafts you may want to run your local server and see documents to be published with a date set in the future. Equally when you generate your site, you may want all documents generated, irrespective of their date. Here, the
--buildFuture switch is your friend.
To run the local server with future documents:
hugo server --buildFuture
To regenerate the site with future documents:
Seeing Into the Past: Flags
By default, Hugo generates and shows on the local server documents with no expiry date. If there is an expiry date set in a document, Hugo will only show that document if the expiry date is set after today.
But as with future dated documents you may want to run your local server and see documents that have been removed because they have passed their expiry date. To see expired documents, add the switch:
You can stack flags, so if you’re running a local server and you want to see drafts and you want to see documents with a future date and you want to see expired documents, you would use the command:
hugo server --buildDrafts --buildFuture --buildExpired.
The advantage of these flags is that you can manage documents in a sensible way while still being able to see what is there and what will be there.