Create Hugo Content Safely with hugo new

No patience for hand-writing front matter every time you start a post? hugo new creates the file, stamps in a title and date, and leaves the writing to you. This guide covers generated front matter, where the file actually lands, and when Hugo reaches for an archetype instead of the default template. 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: don't use sudo to work around a wrong directory or a permissions mistake, inspect the path instead.

1. Start at the site root

hugo new is a site command, so run it from the root of the site you intend to change: 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

Swap in the real path for /path/to/my-site. If your configuration has another name or lives in a configuration directory, confirm that first. A command run successfully from the wrong project can still create a valid-looking file, just in the wrong content tree.

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

That path also gives Hugo a useful content kind when you don't supply one explicitly. 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 from the current clock. With the default archetype on this 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 stay a draft, and add whatever fields your templates actually 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 that second command is just the 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.

4. Choose a content kind when the section isn't enough

Use -k or --kind when the site has an archetype for a particular kind of content. The kind is a site convention Hugo uses to pick 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, and archetypes can add front matter or starter content beyond the bare minimum. Inspect the resulting file rather than assuming every site produces the same header:

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

Run hugo new --help when you need the full list of options. On Hugo 0.123.7, the content subcommand also accepts --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

$ 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 once you've checked it is the right file:

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

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

6. Edit and preview the result

Hugo only creates the starting file. It doesn't write the article, validate your 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, add --buildDrafts for a local check, or use the preview command and options your project already relies on. Don't strip the draft flag just to make a local preview work.

If the build reports a front matter or template error, reopen the generated file and compare its fields against another working page in the same section. A kind-specific archetype may need fields the default archetype never creates.