Convert Hugo Front Matter to YAML Without Losing Your Content

You will convert a Hugo site's front matter to YAML while leaving the Markdown body in place. The workflow makes a backup first, checks the installed Hugo release, runs hugo convert toYAML with the safety switch it requires for in-place changes, and verifies the result. Allow about fifteen minutes for a small site, plus time for a backup if the content directory is large.

This guide uses Hugo 0.123.7, installed from Ubuntu on the reference machine. The command's purpose and flags come from hugo-convert-toYAML(1). Hugo writes files, so treat the conversion as a migration rather than a harmless report.

1. Work from the Hugo site root

Open a shell and change to the directory containing your Hugo configuration and content directory. Replace the example path with your site path. This is an ordinary, unprivileged operation:

$ cd /path/to/your-hugo-site
$ test -d content && printf 'content directory found\n'
$ hugo version

On the reference machine, the version check reports:

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

Your build date and vendor details may differ. Record the version before changing files, because conversion details can vary between releases.

2. Make a recoverable backup

Front matter conversion changes files under content. Before running it, copy that directory to a sibling backup. The backup needs enough space for a second copy of your content:

$ cp -a content content.before-toyaml
$ test -d content.before-toyaml && printf 'backup directory created\n'

Checkpoint: compare the directory names and keep the backup until the site has built successfully and the changed files have been reviewed. Do not put the backup inside content, or Hugo may treat it as site content later.

If you use Git, an existing clean commit is another useful recovery point. Do not rely on an uncommitted working tree as your only backup when the content matters.

3. See the command's local contract

Ask the installed binary for help before the write step:

$ hugo convert toYAML --help

The help identifies hugo convert toYAML [flags] [args]. The subcommand has its own --help flag and inherits global options such as --config, --source, --output, --destination, and --unsafe. This guide uses the default site location, so run it from the site root rather than mixing it with an unverified configuration path.

4. Convert the front matter

Run the conversion from the site root:

$ hugo convert toYAML --unsafe

The reference run prints a count such as:

processing 3 content files

The command converts front matter it finds in the content directory. In a controlled test with TOML, JSON, and YAML front matter, all three files were written with YAML delimiters, ---. A page that was already YAML remained YAML, although its fields were normalised by the conversion. The Markdown body stayed below the closing delimiter.

5. Inspect the changed files

First check the file list. With Git, this is the clearest review:

$ git status --short -- content
$ git diff -- content

For a site that is not tracked by Git, inspect a representative file directly:

$ sed -n '1,18p' content/posts/example.md

Expect YAML front matter between --- lines, followed by the original content. Values may be reordered or rendered differently from the input representation. Check dates, booleans, lists, nested values and quoted strings carefully. A conversion that exits successfully is not a proof that your site's meaning is unchanged.

6. Build the site as a verification checkpoint

Run a normal build before removing the backup. If your site uses a non-default configuration, add the same configuration option you normally use:

$ hugo --destination /tmp/hugo-build-check

A successful build should finish without front matter parse errors and should create output under /tmp/hugo-build-check. The destination is temporary and does not alter your site's published directory. If the build fails, stop and read the first front matter error rather than editing many files at once.

When the build and review pass, keep the backup until your next normal deployment or review window. Remove it only as a deliberate housekeeping step, not as part of a blind script.

7. Recover if the conversion is wrong

Do not run another conversion over uncertain output. For a file-level recovery, copy the original from the backup back to its matching path:

$ cp -a content.before-toyaml/posts/example.md content/posts/example.md
$ hugo --destination /tmp/hugo-build-check-recovery

For a Git-managed site, review the diff and restore only the intended paths using your normal version-control procedure. Avoid a broad restore if other content changes were made after the backup. If you used a complete backup and need to recover several files, copy the affected paths explicitly, then rebuild and inspect again.

Common traps

• Running from the wrong directory: Hugo may use a different configuration or fail to find the expected content tree. Confirm pwd, test -f hugo.yaml, test -f hugo.toml, or test -f config.toml as appropriate for your site.
• Expecting a preview: toYAML is a converter. The documented output and the reference run show processing followed by file writes; use a backup and a diff for review.
• Using root without need: conversion of a site in your own working directory should not require sudo. Elevated privileges can leave root-owned files behind and make recovery harder.
• Deleting the backup too early: retain it until a build and content review have passed. The command has no documented undo option.