Docs on HugoKit

Broken links and missing CSS after deploying to GitHub Pages

Mon, 01 Jan 0001 00:00:00 +0000

The site is fine on localhost:1313. You deploy it, open https://you.github.io/my-blog/, and get unstyled HTML: the text is there, the CSS is gone, the images 404, and half the links go nowhere.

Nothing is wrong with your build. The problem is that your site no longer lives at the root of a domain.

What’s actually happening

A GitHub Pages project site is served from a subpath: https://you.github.io/my-blog/, not https://you.github.io/.

Locally, your site is at the root, so a template that writes /css/main.css works. In production that same path resolves to https://you.github.io/css/main.css – one level above your site, where nothing exists. Every absolute path you wrote by hand is now pointing outside your own site.

Editing your config

Mon, 01 Jan 0001 00:00:00 +0000

Your Hugo config is the file most likely to break a site, and the one you edit least often – so you never quite remember what the keys are called. HugoKit gives it a form, a raw editor, and one rule: nothing is written to disk until you’ve seen the diff.

Two tabs, one file

The Config page opens your site’s config file – TOML, YAML or JSON; the format is detected from the file, not assumed.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

HugoKit is a Mac app that runs the Hugo you already use. It doesn’t convert your site, doesn’t move your files and doesn’t need an account – it starts hugo server, checks the site before it ships, and publishes it.

What you need

A Mac running macOS 26 (Tahoe) or later.
A Hugo site. If you don’t have one, HugoKit can create it for you.
Hugo itself is optional. If it isn’t installed, HugoKit installs it during setup.

Install the app

Download the DMG from hugokit.com.
Open it and drag HugoKit into your Applications folder.
Launch it. The app is signed and notarised, so macOS opens it without the “unidentified developer” dialog.

First launch

The setup wizard has four steps: Welcome, Hugo, Add Your First Site, and You’re All Set. You can leave it at any point with Esc, and the middle steps have a Skip Setup link. To see it again later, choose Help → Show Welcome Screen.

Publishing to GitHub Pages

Mon, 01 Jan 0001 00:00:00 +0000

HugoKit publishes to GitHub Pages the way you’d do it by hand: it commits your project, pushes it, and lets GitHub Actions build the site. The difference is that you never open a terminal, and the checks that usually bite you run first.

Before you start

You need a GitHub account and a repository for the site. HugoKit can’t create the repository for you – make an empty one on github.com first, public or private, both work.

Running the server

Mon, 01 Jan 0001 00:00:00 +0000

HugoKit runs the same hugo server you’d run in a terminal. It just remembers the flags, picks a free port, and turns Hugo’s output into something you can read.

Start and stop

Select the site and use Start Server in the toolbar; it becomes Stop Server while the server runs. The Server page has the same actions, plus Restart.

The exact command is written to the log before it runs, so you can always see what HugoKit asked Hugo to do:

Editing content

Mon, 01 Jan 0001 00:00:00 +0000

The Content page lists your pages and lets you make the small edits that don’t need a full editor – a title, a date, a tag, a typo. It’s built for exactly those changes, and it leaves the writing to your own editor.

The Content page

Open Content for the selected site and HugoKit counts what’s there – pages, sections, words and images, and how many are drafts, future-dated or expired – and lists the files. Open one and you get a preview, a front matter inspector, and a Raw tab.

Snapshots and undo

Mon, 01 Jan 0001 00:00:00 +0000

HugoKit edits files that are yours – a config, a post, a template a preflight fix rewrites. The one mistake an app like this can’t afford is changing your text and leaving you no way back. So it doesn’t get the chance: before HugoKit writes to any file in your site, it snapshots the file as it was.

When a snapshot is taken

Every write HugoKit makes goes through the same door. That covers all four places the app touches your files:

hugo server won't start: port already in use

Mon, 01 Jan 0001 00:00:00 +0000

You run hugo server and get:

Error: listen tcp 127.0.0.1:1313: bind: address already in use

Something is already listening on port 1313. Nine times out of ten it’s a hugo server you started earlier – in a terminal tab you closed without stopping it, or in another window.

The quick way out: use another port

hugo server --port 1314

That’s it. Nothing is broken; two servers just can’t share one port.

Hugo without the terminal

Mon, 01 Jan 0001 00:00:00 +0000

Hugo is a command-line tool, and using it means knowing a handful of commands, a handful of flags, and which of them you need right now. That’s a small amount of knowledge, and it’s fine – until it isn’t. Until you write once a month and have to relearn it every time. Until the flag you need is one you’ve never used. Until something goes wrong and the error is about Go template internals.

Publishing over SFTP

Mon, 01 Jan 0001 00:00:00 +0000

If you have a web host rather than a GitHub Pages site, HugoKit builds the site on your Mac and uploads it. It only sends the files that actually changed.

Before you start

You need the SFTP details your host gave you: host, username, password (or an SSH key), and the folder your site is served from – often /public_html.

Set your real baseURL in hugo.toml first. Unlike the GitHub Pages path, HugoKit does not override it for an FTP build: the site is built exactly as your config says. Preflight will stop you if it still points at localhost.

Themes and template preview

Mon, 01 Jan 0001 00:00:00 +0000

Hugo’s layouts are the part you can’t see until the page renders. HugoKit’s Themes page lists what’s installed, and Template Preview renders any single layout file next to its source – without you guessing which URL exercises it.

Installed themes

The Themes page lists every theme in your site’s themes/ folder. Removing one deletes themes/<name> from disk; nothing else in the site is touched.

New Blank Theme

New Blank Theme scaffolds a placeholder theme in themes/<name> – minimal layouts and styles to build on, not a finished design. It runs Hugo’s own hugo new theme underneath.

A desktop app for Hugo

Mon, 01 Jan 0001 00:00:00 +0000

Hugo is a command-line tool. There’s no official app, no window, no buttons – you drive it from a terminal. So it’s a reasonable thing to go looking for: a GUI, a desktop app, a Mac app, something with an interface. This page is the honest answer to that search.

HugoKit is a native Mac app for Hugo

HugoKit runs the same Hugo binary you already have and puts a window around it. Start the server, preview your pages, check the site and publish it – from one place, with the flags on buttons instead of in your memory. It’s free, it’s native SwiftUI (no Electron), and it needs no account.

Build flags

Mon, 01 Jan 0001 00:00:00 +0000

Every publish builds the site first. The Build section on the Deploy page decides how – the same Hugo flags you’d type by hand, set per site and shown as the exact command line before anything runs.

The flags

On the Deploy page, per site:

--gc – run Hugo’s garbage collection after the build, clearing stale entries from its cache.
--minify – minify the built output.
Environment – the build environment Hugo runs in (--environment), for config and templates that switch on it. Leave it blank for Hugo’s default.

Both flags are on by default – exactly what every HugoKit build did before this was a setting, so upgrading doesn’t change what your site builds to. The command line under the toggles updates as you change them, so you always see what will run: hugo --gc --minify, or hugo, or hugo --gc --minify --environment staging.

LiveReload isn't reloading

Mon, 01 Jan 0001 00:00:00 +0000

You save a file. The browser sits there. Or it refreshes and shows exactly what it showed before.

Before you change anything, work out which half is broken: did Hugo see the file change, or did the browser fail to act on it? The server log answers that. Save the file and watch the terminal:

Change detected, rebuilding site (#1).
Total in 42 ms

You see that line → Hugo saw it. The problem is in the browser.
You see nothing → Hugo never noticed the file. The problem is the watcher.

Those are two completely different bugs, and guessing wrong costs you an hour.

Preflight – what it checks and why

Mon, 01 Jan 0001 00:00:00 +0000

A Hugo site that builds perfectly on your Mac can still land broken on the web. The build isn’t the thing that breaks – the paths are. Preflight runs before every publish and looks for exactly the failures that only show up once the site is live.

When it runs

Automatically, before every publish. If it finds nothing, the publish just continues. If it finds something, you get the report and decide what to do.

Site health

Mon, 01 Jan 0001 00:00:00 +0000

Preflight runs before a publish and blocks the things that break a deployed site. Site health is the other half: it doesn’t block anything, and it tells you what the site is like to read – broken links, images without alt text, a config key Hugo deprecated two versions ago.

Open it with ⇧⌘H, from the Dashboard’s health card, from the Config page, the View menu or the command palette (⌘K).

Hugo vs WordPress

Mon, 01 Jan 0001 00:00:00 +0000

Hugo and WordPress both build websites, and roughly there the similarity ends. WordPress is a database-driven CMS: content lives in a database, you edit it in a browser admin, and a server assembles each page when someone visits. Hugo is a static site generator: content lives in Markdown files, you build the whole site into plain HTML once, and a host just serves those files.

Neither is “better”. They make different trade-offs, and the right pick depends on who runs the site and what it needs to do.

Raw HTML omitted: your HTML disappears from Markdown

Mon, 01 Jan 0001 00:00:00 +0000

You put a <div>, an <iframe> or a <details> block in a Markdown file. The page builds fine – and the HTML is gone. In the output there’s a comment where your markup should be:

<!-- raw HTML omitted -->

And in the build log:

WARN Raw HTML omitted while rendering "/content/about.md";
 see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe

Why

Hugo renders Markdown with Goldmark, and Goldmark refuses to pass raw HTML through by default. It’s a safety default: if your Markdown comes from somewhere you don’t control, letting it emit arbitrary HTML – <script> included – is a hole. Hugo would rather drop it than trust it.

GitHub Pages shows your README instead of your Hugo site

Mon, 01 Jan 0001 00:00:00 +0000

You push your Hugo project to GitHub, enable Pages, and the site that comes up is your README.md – rendered as a web page, with the wrong theme and none of your content.

GitHub isn’t building your Hugo site. It’s running Jekyll on the folder you pushed, and Jekyll, finding no index.html, serves the README instead.

Why it happens

Pages has two very different modes:

Deploy from a branch – GitHub takes the files on a branch and runs them through Jekyll. Fine for a Jekyll site or for pre-built HTML. It has no idea what Hugo is: your content/, layouts/ and hugo.toml mean nothing to it, and public/ isn’t in the repository at all, because your .gitignore excludes it.
GitHub Actions – a workflow you supply builds the site and publishes the result. This is the mode a Hugo site wants.

If Pages is set to Deploy from a branch → main → / (root) while your repo holds Hugo source, you get the README. Every time.

Hugo builds fine, but the page is blank

Mon, 01 Jan 0001 00:00:00 +0000

The build succeeds. The server starts. And the page in the browser is empty – no error, no content, nothing to click. Somewhere in the log:

WARN found no layout file for "html" for kind "home"

The exact wording moves around between Hugo versions, but the shape is always the same: kind and no layout file.

Why

Hugo doesn’t render Markdown to HTML on its own. It hands each page to a template, and the template decides what the HTML looks like. If it can’t find a template for a page, it doesn’t guess and it doesn’t fail – it writes the page with nothing in it and moves on.

Hugo ignores a setting in hugo.toml

Mon, 01 Jan 0001 00:00:00 +0000

You add a setting to hugo.toml. You restart the server. Nothing changes. No error, no warning – Hugo builds happily and behaves as if the line isn’t there.

Look at where the line sits:

baseURL = "https://example.com/"
title = "My site"

[params]
 author = "Anders"
 description = "A site"

theme = "papermod"

theme is at the bottom, at the left margin, unindented. It looks top-level. It isn’t.

Why

TOML has no braces. A [section] header opens a table, and every key after it belongs to that table until the next header. Indentation is decoration; TOML doesn’t read it.

error calling partial: the two things it usually means

Mon, 01 Jan 0001 00:00:00 +0000

The build stops in the middle of a template:

Error: error calling partial: partial "header.html" not found

or, more alarmingly:

Error: error calling partial: runtime error: invalid memory address
 or nil pointer dereference

Two different messages, two different causes, and both are one-line fixes.

“partial … not found”

Hugo looked for the file and it wasn’t where it looks. Three things to check, in order:

1. The name has to match the file, extension included.

Hugo won't build: front matter errors

Mon, 01 Jan 0001 00:00:00 +0000

You add a post, Hugo refuses to build, and the error is about YAML rather than about anything you recognise as your problem. Here are the three you’ll actually meet.

“mapping values are not allowed in this context”

Error: failed to unmarshal YAML: yaml: line 2: mapping values are
 not allowed in this context

There’s an unquoted colon in a value:

---
title: Hugo: a static site generator
---

YAML reads the first colon as this is a key, and then finds a second one and gives up. Quote the value:

Deprecation warnings after upgrading Hugo

Mon, 01 Jan 0001 00:00:00 +0000

You upgrade Hugo. The site still builds. But the log has grown a paragraph:

WARN deprecated: .Site.IsServer was deprecated and will be removed
 in a future release. Use hugo.IsServer instead.

It builds today. That’s the part worth understanding.

Why you shouldn’t leave it

Hugo removes things in three steps: first a warning, then an error, then the feature is gone. The steps are spread across releases, so a warning you ignore is a build that fails on some future Tuesday when you upgrade for an unrelated reason – and by then you’ll have forgotten what the warning said.

GitHub Pages keeps serving the old version of your site

Mon, 01 Jan 0001 00:00:00 +0000

You publish. Git accepts the push. GitHub reports no failure. And hugokit.com – or whatever your site is called – shows exactly what it showed yesterday.

Before you look at anything else: open the site in a private window. A stale service worker or a cached HTML file explains this often enough to be worth thirty seconds.

If it’s still old, the cause is almost always this one.

Two deploy mechanisms, one repository

GitHub Pages can get its files from one of two places, and it uses exactly one:

Your post doesn't show up

Mon, 01 Jan 0001 00:00:00 +0000

You wrote the post. The file is in content/posts/. Hugo builds without a word. And the post isn’t on the site – not on the front page, not at its own URL, not anywhere.

Hugo isn’t losing it. Hugo is hiding it, deliberately, for one of three reasons.

1. It’s a draft

---
title: "My post"
draft: true ← here
---

hugo new writes draft: true into every file it creates, and it’s easy to forget it’s there. Drafts are excluded from every build, including the dev server.

Hugo can't build SCSS: you need the extended version

Mon, 01 Jan 0001 00:00:00 +0000

You add a theme, run hugo server, and the build stops with something like:

error: error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

Nothing is wrong with your site or your theme. Your Hugo just can’t compile SCSS.

Why this happens

Hugo ships in two builds:

Standard – the plain hugo binary.
Extended – the same, plus a Sass/SCSS compiler (and WebP encoding).

Most themes style themselves in SCSS, and only the extended build can turn that into CSS. Run one of those themes on standard Hugo and the transform fails – that’s the TOCSS error (TOCSS is Hugo’s “to CSS” step).