Docs
How to run, check and publish a Hugo site with HugoKit – and how to fix the Hugo problems it checks for.
Start
6 pages- Your first Hugo site Start with nothing installed: get the app, let it install Hugo, create a site and see it running in your browser.
- Getting started Bring an existing Hugo site into HugoKit, or create a new one, and get the local server running.
- Hugo without the terminal See which everyday Hugo commands have a control in HugoKit, and which jobs still belong in the terminal.
- A desktop app for Hugo A closer look at running Hugo from a native Mac app, and where that differs from using a browser-based CMS.
- Hugo vs WordPress A practical comparison of Hugo's file-based workflow and WordPress's browser-based CMS.
- Working on a Hugo site with an AI agent A Hugo project is files on disk, which makes it cheap for a coding agent to work in. What that saves, what it doesn't, and how to set the repo up for it.
Running Hugo
1 pageWorking in the app
5 pages- Editing your config Edit TOML, YAML or JSON as fields or raw text, with a diff before HugoKit saves anything.
- Editing content Browse the files in a site, adjust front matter and make the small edits that do not need a full editor.
- Snapshots and undo See exactly what HugoKit changed and restore one file or the whole operation.
- Themes and template preview See the themes already in a site, create a blank one and preview layouts while you work.
- Site health Get a practical read on broken links, missing alt text, large images, old configuration and content gaps.
Publishing
4 pages- Publishing to GitHub Pages Connect a Hugo site to a repository and publish it to GitHub Pages with GitHub Actions or a locally built `gh-pages` branch.
- Publishing over SFTP Connect a regular web host over SFTP or FTP, verify the login and publish only what changed.
- Build flags Configure garbage collection, minification and the Hugo build environment per site.
- Preflight – what it checks and why Catch broken paths, configuration and assets before they reach the published site.
Fixing common Hugo problems
13 pages- Broken links and missing CSS after deploying to GitHub Pages The site works locally, but GitHub Pages has lost its CSS, images or links below the repository subpath.
- hugo server won't start: port already in use Another process already has port 1313. Reuse it, stop it or choose another port.
- LiveReload isn't reloading You saved the file, but nothing moved. Check whether Hugo's watcher or the browser connection missed the change.
- Raw HTML omitted: your HTML disappears from Markdown Your HTML is still in the Markdown file; Goldmark has chosen not to render it.
- GitHub Pages shows your README instead of your Hugo site Your repository is online, but Pages is serving the README instead of the Hugo build.
- Hugo builds fine, but the page is blank Hugo built the page but had no layout to render it with. Add the template that matches the page kind.
- Hugo ignores a setting in hugo.toml Hugo accepts the config but ignores one setting. It is usually nested under the wrong TOML table or YAML level.
- error calling partial: the two things it usually means The build stopped in a partial. Check the file name first, then the context passed into it.
- Hugo won't build: front matter errors A front matter error looks cryptic, but the usual causes are colons, dates, quotes, indentation or delimiters.
- Deprecation warnings after upgrading Hugo The site still builds, but Hugo is warning that a template API or configuration key is on its way out.
- GitHub Pages keeps serving the old version of your site The push worked, but the site still looks unchanged. Check the Pages source, workflow and cache.
- Your post doesn't show up The file exists, but Hugo has left it out of the build. One of three publication states usually explains it.
- Hugo can't build SCSS: you need the extended version The theme may be fine – this error usually means the standard Hugo binary is trying to compile SCSS.