Hugo’s local Server

When we are working on our content, we often like to examine the resulting pages immediately. To generate an immediate (local) preview, we can run Hugo in its server mode.

A command like the following in the root of a project starts the Hugo server:

hugo server -D --minify --navigateToChanged 

The HTML pages are rendered into memory and the site is served under http://localhost:1313 by default.

• The flag -D lets Hugo include drafted files. All files created with hugo new are usually configured as drafts, using draft: true in the front-matter. When a Markdown file is ready for publishing, we need to remove this entry or change it to draft: false.

• The flag --minify tells Hugo to remove unnecessary whitespace from the resulting code.

• The flag --navigateToChanged tells the server to relay the page of the last changed file to the browser. As soon as we save a file the corresponding page pops up in the browser.

Set a reasonable auto-save delay

Some editors are saving our work so fast by default, that nearly every keystroke leads to a new file version and the regeneration of the corresponding page. When we are in the process of changing sensitive content like front-matter parameters this can easily bring down Hugo’s server, because Hugo can’t process inconsistent files. Then we have to restart the server, which is not a big deal, but gets annoying after a while. It’s better to set the auto-save delay to a bigger value, which lets us save consistent file versions manually.

Adding your first content

To generate a new Markdown file, we go to the root folder of our project and use a command like

hugo new blog/first.md

The new file is created in the folder content/blog. It already contains a front-matter section with some reasonable entries or placeholders to start with.

The title, date and description parameters are mandatory for Perplex as they are for many other themes. The pages headers, page sorting and the navigation depends on them.

1
2
3
4
5
6
7
8

---
title: First 
description: Description placeholder
date: 2022-07-01T21:22:27+02:00
categories: []
tags: []
draft: true
---

The title is guessed from the file name and the date from the moment we ran the hugo new command.¹

The Markdown content begins after the front-matter. Hugo will update our site in the browser as soon as we save a changed version of the file. When we make mistakes, Hugo will display a descriptive error message on its console and in the browser (if Hugo’s server is providing the pages).

Example session

Show all the steps described above