Docs
How to run, check and publish a Hugo site with HugoKit – and how to fix the Hugo problems it checks for.
Start
4 pages- Getting started Install HugoKit, add a Hugo site and start the server. Setup takes a few minutes, and you don't need the terminal for any of it.
- Hugo without the terminal A command-by-command map from the Hugo CLI to HugoKit – what each button actually runs, what it does that no command does, and the parts where the terminal is still the honest answer.
- A desktop app for Hugo Hugo is a command-line tool with no GUI of its own. HugoKit is a native Mac app that puts a window around it – run, preview, check and publish, no terminal. How a desktop app differs from a Hugo CMS, and who each one suits.
- Hugo vs WordPress Two very different ways to build a website – a static site generator and a database-driven CMS. Where each one wins, who should choose which, and where HugoKit fits if you like Hugo but not the terminal.
Running Hugo
1 pageWorking in the app
5 pages- Editing your config Edit hugo.toml from HugoKit – a visual form for the fields you actually change, a raw text tab for everything else, and a diff you approve before anything is written.
- Editing content Edit a page's front matter in a panel beside the file, see page bundles as one entry, and rename a tag everywhere it appears – from HugoKit's Content page.
- Snapshots and undo Before HugoKit writes to any file in your site, it keeps a copy – every change is recorded as a diff, and undo works per file or per operation.
- Themes and template preview See a site's installed themes, scaffold a blank one to build on, and render any layout file live with Template Preview (⇧⌘T).
- Site health A score out of 100 for a Hugo site: broken links, missing alt text, oversized images, deprecated config, front matter gaps and build regressions – with the issues listed out.
Publishing
4 pages- Publishing to GitHub Pages Connect a Hugo site to a GitHub repository and publish it to GitHub Pages from HugoKit – cloud builds, local builds, and the subpath trap that breaks most first deploys.
- Publishing over SFTP Upload a Hugo site to your own web host from HugoKit over SFTP or plain FTP – what to fill in, how the smart sync works, and why passwords need sshpass.
- Build flags Set Hugo's build flags per site in HugoKit – garbage collection, minify and a build environment – with the exact command line shown before it runs.
- Preflight – what it checks and why Before every publish, HugoKit builds your Hugo site and checks the config, baseURL, assets, templates and static JavaScript – then offers to fix what it finds, as a diff you approve.
Fixing common Hugo problems
13 pages- Broken links and missing CSS after deploying to GitHub Pages Your Hugo site works locally but loses its CSS on GitHub Pages. The cause is the repository subpath in baseURL – and relURL doesn't fix it the way you'd expect.
- hugo server won't start: port already in use Hugo exits with "address already in use" on port 1313. Find what's holding the port, free it, or just run on another one.
- LiveReload isn't reloading You save a file and the Hugo dev server does nothing – or reloads with the old content. Work out whether Hugo saw the change or the browser ignored it.
- Raw HTML omitted: your HTML disappears from Markdown Hugo replaces the HTML in your Markdown with an <!-- raw HTML omitted --> comment. Here's why Goldmark does that, and the two right ways to get your markup back.
- GitHub Pages shows your README instead of your Hugo site You pushed your Hugo project and GitHub Pages serves the README as the homepage. The Pages source is set to a branch, so GitHub is running Jekyll on your source.
- Hugo builds fine, but the page is blank Hugo says "found no layout file" and writes an empty page. Nothing is broken – Hugo just has no template for that kind of page, and the fix is one file with the right name.
- Hugo ignores a setting in hugo.toml Your theme, your baseURL or your title has no effect – and Hugo says nothing. In TOML, everything after a [section] header belongs to that section, including the line you just added at the bottom.
- error calling partial: the two things it usually means Hugo stops with "error calling partial" or a nil pointer dereference deep inside a template. Almost always it's a missing dot, or a name that doesn't match the file.
- Hugo won't build: front matter errors "mapping values are not allowed", "cannot unmarshal into time.Time", "did not find expected key" – three YAML errors from one Markdown file, and what each one is really telling you.
- Deprecation warnings after upgrading Hugo .Site.IsServer, .Data.Pages, blackfriday, canonifyURLs – Hugo warns before it removes, so a warning today is a broken build a few releases from now. Here's what each one wants instead.
- GitHub Pages keeps serving the old version of your site You pushed. The build was green. The live site is unchanged. Usually two deploy mechanisms are fighting over the same repository – and only one of them is winning.
- Your post doesn't show up The file is there, the build is clean, and the page doesn't exist. Hugo hides drafts, future-dated posts and expired ones by default – three flags, three fixes.
- Hugo can't build SCSS: you need the extended version Hugo stops with "TOCSS: failed to transform … this feature is not available in your current Hugo version". It means your Hugo isn't the extended build. How to install extended and make sure it stuck.