Create a Clean Hugo Site Skeleton with hugo new site

hugo new site lays down the standard folders and a configuration file for a brand new Hugo project, ready for a theme and content. The examples use Hugo 0.123.7, installed here as the Ubuntu package build 0.123.7-1ubuntu0.3+esm2.

Allow about ten minutes. You need a shell, a writable parent directory and Hugo installed. This command creates directories and a configuration file, nothing more: it doesn't install a theme, create content or publish anything. The examples write under /tmp; use a deliberate project path for a real site.

1. Check the installed Hugo version

Start with a read-only check so the command and its version are clear:

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ command -v hugo
/usr/bin/hugo

Your build date or path can differ. This page documents Hugo 0.123.7 specifically; if you're on a different release, check its own help output before scripting around messages or generated files.

2. Create the site in an empty directory

Choose a path that doesn't already contain work you care about. Swap in your intended absolute or relative path for /path/to/project:

$ hugo new site /path/to/project
Congratulations! Your new Hugo site was created in /path/to/project.

If the final directory doesn't exist, Hugo creates it along with the required parents. A successful run creates these top-level directories:

$ find /path/to/project -maxdepth 1 -mindepth 1 -type d -printf '%f\n' | sort
archetypes
assets
content
data
i18n
layouts
static
themes

It also creates hugo.toml. With the installed default format, its starting values are equivalent to:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

That URL, language and title are just starter values, not anything Hugo has discovered about your actual project. Change them before building a site for real users.

3. Pick a configuration format deliberately

The default is TOML. Select YAML or JSON at creation time if that matches your existing tooling:

$ hugo new site --format yaml /path/to/yaml-project
$ test -f /path/to/yaml-project/hugo.yaml && echo 'created hugo.yaml'
created hugo.yaml

$ hugo new site --format json /path/to/json-project
$ test -f /path/to/json-project/hugo.json && echo 'created hugo.json'
created hugo.json

--format changes the configuration file's format and filename. It does not convert an existing configuration file, and it doesn't touch content format either. The manual accepts only toml, yaml or json; anything else fails with a non-zero status.

4. Understand the empty-site boundary

A skeleton is not a working, themed website. The generated directories are empty apart from the default archetype, and Hugo adds no theme on its own. The command's own suggested next steps are to create or install a theme, set the theme property in the configuration file, create content with hugo new content, then run the server with hugo server --buildDrafts.

Keep those actions separate from site creation itself. Edit the configuration with your real base URL and title first, then add the theme and content you've chosen. No elevated privileges are needed when the project lives in a directory you own; don't use sudo just because Hugo creates several folders.

5. Treat --force as an explicit overwrite boundary

Without --force, Hugo refuses to initialise a directory that already exists and isn't empty:

$ hugo new site /path/to/existing-project
Error: /path/to/existing-project already exists and is not empty. See --force.
$ printf 'exit status: %s\n' "$?"
exit status: 1

$ find /path/to/existing-project -maxdepth 1 -mindepth 1 -printf '%f\n' | sort
$ git -C /path/to/existing-project status --short

Use --force only once you've checked the contents and genuinely intend to initialise there:

$ hugo new site --force /path/to/existing-project
Congratulations! Your new Hugo site was created in /path/to/existing-project.

6. Recover from a wrong path or format

If you created a brand-new skeleton at the wrong path with nothing worth keeping, stop and inspect it before removing anything. The removal itself is irreversible unless you have a backup:

$ find /path/to/wrong-project -maxdepth 2 -print
$ du -sh /path/to/wrong-project