Create a Clean Hugo Site Skeleton with hugo new site

You will finish with a new Hugo project directory containing the standard site folders and a configuration file, 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, but it does not 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. The manual page documents this behaviour for Hugo 0.123.7. If you are following a different release, check its help output before scripting around messages or generated files.

Checkpoint: confirm that hugo new site --help shows the subcommand and that the available format values are toml, yaml and json.

2. Create the site in an empty directory

Choose a path that does not already contain work you care about. Replace /path/to/project with your intended absolute or relative path:

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

If the final directory does not exist, Hugo creates it and 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 initial values are equivalent to:

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

The example URL, language and title are starter values, not details Hugo has discovered about your project. Change them before building a site for 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 format and filename. It does not convert an existing configuration file, and it does not select a content format. The manual accepts only toml, yaml or json; an unsupported value fails with a non-zero status.

Checkpoint: list the new directory and confirm that it contains exactly the configuration format you selected. Do this before adding another configuration file, because multiple files can make later configuration checks harder to reason about.

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 does not add a theme. The command's own next steps are to create or install a theme, set the theme property in the configuration file, create content with hugo new content, and then run the server with hugo server --buildDrafts.

Keep those actions separate from site creation. First edit the configuration with your real base URL and title. Then add the theme and content you have chosen. No elevated privileges are needed when the project is in a directory you own; do not 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 is not 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

This refusal protects an existing project from accidental initialisation. Inspect the directory before deciding what to do:

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

Use --force only when you have checked the contents and intend to initialise there:

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

--force does not mean "delete this directory". Existing files remain, but Hugo can create or replace files needed for the site skeleton. Treat this as a state-changing operation. Make a backup or commit first, and review the resulting directory and version-control diff afterwards.

6. Recover from a wrong path or format

If you created a brand-new skeleton at the wrong path and it contains no work you want to keep, stop and inspect it before removing it. The removal is irreversible unless you have a backup:

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

Only after that review, and only when the path is the newly created project, remove it explicitly with rm -r -- /path/to/wrong-project. Never substitute a broad parent directory or an unresolved shell variable. If the project contains content or a configuration you want, keep it and edit or move the files instead. A different configuration format generally means creating a new empty skeleton, then migrating settings deliberately; hugo new site is not a conversion tool.