Hugo server preview

The CSS preview is a good approximation, but it’s still an approximation: no layouts, no partials, and shortcodes rendered from stand-in templates. If Hugo is installed on the machine Emet is running on, you can skip all that and look at the real page. Emet loads it from a hugo server in the preview pane, and Hugo’s live reload keeps it current.

This needs Hugo on the same machine as Emet, so it’s only available in two situations:

In the desktop app, where Emet starts and manages the server for you.
In local development mode (npm run dev with HUGO_ROOT set), where you run hugo server yourself and Emet connects to it.

On a GitHub-hosted site there’s no Hugo to talk to, so the option doesn’t appear.

Switching to it#

When a Hugo server is available, the preview header gains a Markdown / Hugo toggle. Markdown is the CSS preview; Hugo is the server. Your choice is remembered.

The page Emet loads is worked out from the entry: the section’s permalink pattern (or Hugo’s default, the file’s path under content/), a url in the frontmatter if there’s one, and the language prefix on multilingual sites. The frame’s toolbar shows the resulting URL, with buttons to reload it and to open it in a browser tab.

Because the server reads files from disk, it shows what you’ve saved, not what you’ve typed. Save (Ctrl+S) and Hugo rebuilds and reloads the frame on its own. The page follows your site’s own light and dark logic rather than Emet’s theme setting.

In local development#

Emet expects the server at http://localhost:1313, which is where hugo server puts it by default. Run it from your Hugo site root with drafts enabled, since that’s what you’ll mostly be previewing:

hugo server --buildDrafts --buildFuture

If your server is somewhere else, or you’d rather not have the toggle at all, say so in cms.yaml:

preview:
  hugo_server:
    url: http://localhost:1414
    enabled: false   # removes the toggle entirely

In the desktop app#

The desktop app starts a Hugo server itself the first time you open an entry, on a free port, bound to 127.0.0.1 and with --buildDrafts and --buildFuture. It looks for hugo on your PATH (with which, or where on Windows) and gives up with an error if it isn’t there or doesn’t report ready within 30 seconds. There’s storage for a custom binary path but no UI for setting it yet, so Hugo needs to be on the PATH. The server stops when you quit. Local Hugo server has the internals.

When the server isn’t running#

Emet doesn’t fall back to the CSS preview on its own. If it can’t reach the server you get a Hugo Server Not Running message with a Retry button (in the desktop app it reads Hugo Server Starting… and Retry also restarts the server). Start your server, or flip the toggle back to Markdown to carry on with the CSS preview.

What you give up#

The styled-preview toggle, scroll sync and annotation mode are features of the CSS preview and disappear while the Hugo preview is showing. In exchange you get the actual site, which is usually the better trade once you’re past the writing stage and into checking how it looks.