The local Workflow
While working on our content, we like to examine the result. To generate an immediate local preview, we run Hugo in server mode.
The following instructions assume, that you have opened a terminal and are in your project root containing a copy of this documentation project.
Hugo’s server mode
hugo server -D --navigateToChanged
This command in the root of a project starts the Hugo server. All 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 withhugo new
includedraft: true
in the front-matter. When a Markdown file is ready for publishing, we need to remove this entry or change it todraft: false
.The flag
--navigateToChanged
tells the server to relay the page of the last changed file to the browser. When we save a changed content file the corresponding page gets served in the browser.
Your first content
To generate a new blog entry use a command like
hugo new blog/first.md
The new file is created in the folder content/blog. It has a front-matter section with some parameter keys for meta-data. They contain auto-generated values, or placeholders, or are empty.1 The first lines of the front-matter look like
The author
value is optional, the title
and the date
are mandatory. The title
is just guessed from the file name — you probably want to change it. The date
contains the moment when we ran the hugo new
command in a special format. You can also change it but need to be very careful, because typos may lead to errors.
At first, we ignore the following empty resources
section and its parameters. We’ll catch up later with that.
At the end of the front-matter are the taxonomy keys with empty lists (squared brackets) as values. Here you can add one or more keywords (comma-separated).
Our Markdown content begins after the front-matter.
**Placeholder**: Put your own summary paragraph here instead of this one.
{.p-first}
<!--more-->
All new files contain this placeholder with a special attribute for the first paragraph and the more tag to mark this first paragraph as the page summary. You are encouraged to replace this placeholder with your summary now or later. It’s essential for cards and other page previews.
Your following content may be simple text without markup in the beginning.
As soon as you save your file, Hugo’s server will update your site in the browser. Should you make mistakes, Hugo will display a descriptive error message on its console or in the browser.
Editor usage
The following tips may improve your editing experience.
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 cause Hugo’s server to throw an error, because Hugo can’t render inconsistent files.
This 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.
Editor links in the local preview
A few editors offer protocols to open files with a special link. For now, the theme provides a link to open the content file in a local instance of Visual Studio Code. This link is only present if Hugo runs in server mode and a local file exists. It’s placed in the date at the top or the bottom of regular pages. Because taxonomy pages don’t show a date, the link is placed in the title.