Create Safe Hugo Content Files with hugo new content

You will finish with a new Hugo content file in the intended section, containing generated front matter and the right kind of page. The examples were checked with Hugo 0.123.7 on Linux. Allow about ten minutes for a first page, including a quick review of the result.

You need Hugo installed and a Hugo project directory containing its configuration file. The command must run from the project root, not from content/. It writes a file, but it does not publish it, start a server or require elevated privileges.

1. Check the version and project root

Start by confirming which Hugo you are using and locating the project configuration:

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ pwd
/srv/www/example
$ ls hugo.toml
hugo.toml

The exact version line will differ on your machine. If ls hugo.toml fails, check for hugo.yaml or hugo.json instead. Change directory to the project root before continuing:

$ cd /srv/www/example

Checkpoint: the next command should create a path below this project. If the printed path points at an unexpected directory, stop and fix the working directory first.

2. Create an ordinary Markdown post

Pass a path relative to the content directory. A dated-looking name is not required; the filename and its parent section are your choice:

$ hugo new content posts/first-deploy.md
Content "/srv/www/example/content/posts/first-deploy.md" created

On a standard project, Hugo creates content/posts/first-deploy.md. Inspect it before adding prose:

$ sed -n '1,12p' content/posts/first-deploy.md
+++
title = 'First Deploy'
date = 2026-09-24T12:55:43+01:00
draft = true
+++

The title is inferred from the filename, the date is set automatically, and a new file is a draft by default in the tested installation. The timestamp will naturally be different. Keep draft = true while the page is unfinished. Remove or change it only when your site's publishing workflow is ready.

3. Let the path express the content section

Hugo guesses the kind of content from the path. For example, this creates a page under a documentation section:

$ hugo new content docs/installation.md
Content "/srv/www/example/content/docs/installation.md" created

The section is docs, while the filename is installation.md. This convention makes the URL and template lookup predictable, but it does not mean that every path should be guessed. When the kind matters, say so explicitly.

Use -k or --kind to select a content type:

$ hugo new content --kind tutorial tutorials/backup.md
Content "/srv/www/example/content/tutorials/backup.md" created

If the project or theme has an archetype for tutorial, Hugo uses it. Archetypes are templates for new content, so they may add front matter beyond the title, date and draft fields. Read the generated file rather than assuming the template matches your plan.

4. Check for an existing file before using force

Hugo refuses to overwrite an existing path:

$ hugo new content posts/first-deploy.md
Error: /srv/www/example/content/posts/first-deploy.md already exists

This is a useful guard against losing a draft. Do not use --force as a routine fix. It overwrites the file at the requested path and can destroy edits or front matter. Before an intentional replacement, make a recoverable copy and inspect the target:

$ cp -- content/posts/first-deploy.md /tmp/first-deploy.md.backup
$ sed -n '1,20p' content/posts/first-deploy.md
$ hugo new content --force posts/first-deploy.md
Content "/srv/www/example/content/posts/first-deploy.md" created

That backup is the undo path. Restore it only if you really intend to discard the newly generated file:

$ cp -- /tmp/first-deploy.md.backup content/posts/first-deploy.md

Do not run the force example against a valuable draft until you have a backup outside the target path. The command does not provide a recycle bin.

5. Use a non-default content directory when the project needs one

Projects can mount content somewhere other than the default content directory. Supply that location with --contentDir:

$ hugo new content --contentDir site-content posts/first-deploy.md
Content "/srv/www/example/site-content/posts/first-deploy.md" created

Use the option when the project configuration and repository layout require it. Otherwise, a successful command can still put the file where the site's templates do not look. Verify the actual path in Hugo's output and then check it directly:

$ test -f site-content/posts/first-deploy.md && printf '%s\n' 'content file exists'
content file exists

--contentDir is a path for this invocation. It is not a replacement for fixing a project whose configuration points at the wrong content mount.

6. Open the new file only after creation succeeds

You can ask Hugo to open the generated file with an editor:

$ hugo new content --editor "$EDITOR" posts/release-notes.md

The --editor option is optional. If your editor command needs arguments, test that command separately first. A simpler and less distracting workflow is to create the file, inspect its path and then open it yourself:

$ hugo new content posts/release-notes.md
Content "/srv/www/example/content/posts/release-notes.md" created
$ ${EDITOR:-vi} content/posts/release-notes.md

Do not confuse the filename with the page title. Hugo derives an initial title, but you should edit the front matter if the public heading needs a different spelling or capitalisation.

7. Verify the draft without publishing it

Finish by checking that the file exists, the front matter is present and the draft flag is still clear:

$ test -f content/posts/release-notes.md
$ sed -n '1,10p' content/posts/release-notes.md
+++
title = 'Release Notes'
date = 2026-09-24T12:55:43+01:00
draft = true
+++

If you use the development server, remember that drafts may need the server's draft option to appear. That is a preview concern, not something hugo new content changes. The command itself only creates the source file.