Convert Hugo front matter to TOML without losing your source

You will convert Hugo content front matter to TOML with hugo convert toTOML, while keeping an easy rollback copy of the original files. On this machine the installed package provides Hugo 0.123.7. Allow about 15 minutes for a small site, plus time to review the resulting diff. The conversion changes files, so do not run it against an uncommitted working tree.

Before you start

You need a Hugo site, a shell, and enough free space for a backup. The command operates on the site's content directory and converts the front matter delimiters and values to TOML. It does not publish the site, rebuild your deployment, or convert the site's configuration files. Run it as the account that owns the working tree. sudo is not a normal prerequisite.

Check the exact binary and version first:

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

Your build date or vendor suffix may differ. Keep the version in the change record if the conversion is part of a team migration.

1. Make a reversible backup

Commit or otherwise save the current state before conversion. A Git commit is the clearest recovery point:

$ cd /path/to/example-site
$ git status --short
$ git add content
$ git commit -m 'Save content before TOML front matter conversion'

Only stage content if that is the scope you have reviewed. If the site is not in Git, make a copy outside the source tree with your normal backup tool. Do not rely on a later Hugo build as a backup. A failed or unwanted conversion can still leave files changed.

2. Inspect the command's safety boundary

Read the installed command's help from the site directory:

$ hugo convert toTOML --help
toTOML converts all front matter in the content directory
to use TOML for the front matter.

Usage:
  hugo convert toTOML [flags] [args]

The subcommand itself has no conversion-specific options beyond --help. It inherits Hugo's source, configuration, output, verbosity and safety flags. In particular, --unsafe permits the in-place operation and the manual explicitly says to back up first.

Test the safety guard before enabling it:

$ hugo convert toTOML
Error: command error: Unsafe operation not allowed, use --unsafe or set a different output path

On Hugo 0.123.7, running this from a normal site leaves the content unchanged and returns a non-zero status. That is a useful check that you are in the expected site, but it is not a complete preview. Hugo does not provide a conversion diff mode in this command.

3. Confirm which site and content tree Hugo will use

Hugo resolves the content directory from the site it finds in the current working directory. Look at the files that are about to be affected:

$ pwd
/path/to/example-site
$ find content -type f -print | sort | sed -n '1,40p'
$ git ls-files content | wc -l

Use the inherited --source flag when you deliberately need to read a site relative to another directory:

$ hugo convert toTOML --source /path/to/example-site --help

The source path is not a substitute for checking the target. An absolute path can make it easier to convert the wrong checkout, especially in a release or staging directory. Stop if the file list contains generated output, a mounted volume, or a second site that you did not intend to change.

4. Convert the front matter

From the site root, run the operation with the explicit safety acknowledgement:

$ cd /path/to/example-site
$ hugo convert toTOML --unsafe
processing 184 content files

The count depends on your site. The command rewrites every content file with front matter in the content directory, not just the page you last edited. It normally changes YAML or JSON front matter delimiters to TOML delimiters and serialises the values in TOML syntax. The body below the front matter remains content for Hugo to parse.

Do not interpret --unsafe as a permission to run as root. It is Hugo's acknowledgement that the command may write over the source files. If the command reports a parse error, keep the original backup and investigate the named file before rerunning the whole conversion.

$ git status --short
$ git diff --stat
$ git diff -- content/path/to/page.md

A typical converted header looks like this:

+++
draft = false
tags = ['linux', 'hugo']
title = 'Example page'
+++

The page body is still here.

Hugo 0.123.7 prints a short processing line and exits with status 0 when this operation succeeds. It does not print a per-field migration report, so the diff is where you confirm quoting, arrays, dates, booleans and multiline values.

5. Build and review the converted site

Run a normal build before committing the rewrite:

$ hugo --gc
Start building sites ...
                   | EN
-------------------+----
  Pages            | 184
  ...
Total in ...

The exact totals and timing vary by site. The useful result is a zero exit status and no front matter parse errors. If your build has project-specific checks, run them now as well. A successful conversion command alone does not prove that templates, taxonomies and front matter-dependent logic still behave as intended.

Review the complete change, then commit only the conversion you have checked:

$ git diff --check
$ git diff --stat
$ git diff -- content
$ git add content
$ git commit -m 'Convert Hugo content front matter to TOML'

git diff --check catches whitespace problems, while the ordinary diff lets you spot a value that has changed meaning rather than merely changed syntax.

Recover if the result is wrong

Do not overwrite the backup while reviewing. If the conversion is uncommitted, restore only the affected content from the backup or discard the reviewed working-tree change with your normal Git recovery procedure. If you made the safety commit above, revert it in a new commit:

$ git revert <conversion-commit>

Replace the placeholder with the actual commit ID. This creates an auditable undo commit and does not rewrite shared history. If Hugo stopped part-way through, restore from the pre-conversion commit or backup first, fix the offending front matter, and then run the conversion again. Do not mix hand-edits from a partial run with an unexamined second run.

After recovery, rebuild the site and check git status --short. If the build is failing because a particular value cannot be represented as expected, compare the original header with the generated TOML and make one small, tested correction at a time.

Common traps

• Wrong directory: the command acts on the site Hugo discovers, so check pwd, the config, and the content file list before using --unsafe.
• No backup: the safety flag is not a dry run. It authorises writes; it does not make them reversible.
• Assuming only one page changes: the description says all front matter in the content directory. Review the whole diff.
• Checking only the exit status: a successful rewrite still needs a build and a diff review to catch semantic changes.
• Using sudo: elevated privileges can create root-owned files and hide ordinary permission mistakes. Use them only when your site storage genuinely requires it.