Create Hugo Content Safely with hugo new

You will create a new Hugo content file with generated front matter, check where it was written, and understand when Hugo uses an archetype. The examples target Hugo 0.123.7, the version installed on this machine.

Allow about ten minutes. You need an existing Hugo site and a shell. The normal commands are unprivileged. Do not use sudo to work around a wrong directory or a permissions mistake: inspect the path first.

1. Start at the site root

hugo new is a site command, so run it from the root directory of the site you intend to change. This is the directory containing your Hugo configuration, such as hugo.toml, hugo.yaml or hugo.json.

$ cd /path/to/my-site
$ pwd
/path/to/my-site
$ ls hugo.toml

Replace /path/to/my-site with the real path. If your configuration has another name or lives in a configuration directory, confirm it before continuing. A successful command run from the wrong project can create a valid-looking file in the wrong content tree.

Checkpoint: pwd should print the project root, not the directory where you keep several unrelated sites.

2. Create content at a chosen path

Use the content subcommand and give Hugo a path relative to the site's content directory. This example creates content/posts/first-note.md:

$ hugo new content posts/first-note.md
Content "/path/to/my-site/content/posts/first-note.md" created

The path also gives Hugo a useful content kind when no explicit kind is supplied. Keep the file extension that matches the format you want to edit. The command creates missing directories below the content directory as needed.

Hugo adds a title derived from the filename and a date based on the current clock. With the default archetype on the installed version, a Markdown file looks like this:

+++
title = 'First note'
date = 2026-09-24T12:30:00+01:00
draft = true
+++

Your date will differ. Treat the generated front matter as a starting point: edit the title, decide whether the page should remain a draft, and add the fields your templates require.

3. Confirm the file before editing

Check both the command output and the file on disk. This catches a misspelled section or an unexpected content directory before you start writing:

$ test -f content/posts/first-note.md && echo "file exists"
file exists
$ sed -n '1,12p' content/posts/first-note.md
+++
title = 'First note'
date = 2026-09-24T12:30:00+01:00
draft = true
+++

The date in the second command is only an example. Verify the actual value printed on your machine. If test fails, stop and inspect the path rather than creating another file with a similar name.

Checkpoint: the file exists under the site you selected, its front matter is closed correctly, and the title matches the page you intend to publish.

4. Choose a content kind when the section is not enough

Use -k or --kind when the site has an archetype for a particular kind of content. The kind is a site convention used when Hugo selects an archetype; it is not a request to publish the page immediately.

$ hugo new content --kind note notes/architecture.md
Content "/path/to/my-site/content/notes/architecture.md" created

If the site or its theme provides a matching archetype, Hugo uses it. Archetypes can add front matter or starter content beyond the minimal default. Inspect the resulting file rather than assuming every site produces the same header.

$ sed -n '1,40p' content/notes/architecture.md

Use hugo new --help when you need the command's available options. On Hugo 0.123.7, the content subcommand also accepts options such as --contentDir, --kind, --theme, --editor and --force.

5. Do not overwrite existing content by accident

Hugo refuses to create a file when the target already exists:

$ hugo new content posts/first-note.md
Error: /path/to/my-site/content/posts/first-note.md already exists

This is a useful safety boundary. Open the existing file and decide whether you meant to edit it, choose a new filename, or recover the path from your shell history. The refusal leaves the existing file in place.

$ cp --preserve=all content/posts/first-note.md /tmp/first-note.md.backup
$ hugo new content --force posts/first-note.md
Content "/path/to/my-site/content/posts/first-note.md" created

To undo that deliberate replacement, restore the backup after checking it is the intended file:

$ cp --preserve=all /tmp/first-note.md.backup content/posts/first-note.md

A version-control checkout or restore is preferable when the file is tracked, because it preserves the project's normal audit trail. The backup example is only for a local recovery point.

6. Edit and preview the result

Hugo only creates the starting file. It does not fill in the article, validate your site's front matter schema, or make a draft public. Edit the file with your normal editor, then build or serve the site using its usual workflow.

$ ${EDITOR:-vi} content/posts/first-note.md
$ hugo --buildDrafts

The build command is separate from hugo new. If the page is still marked draft = true, include --buildDrafts for a local check, or use the preview command and options already established by your project. Do not remove the draft flag merely to make a local preview work.

If the build reports a front matter or template error, reopen the generated file and compare its fields with another working page in the same section. A kind-specific archetype may require fields that the default archetype does not create.