Back Up Before hugo convert toJSON

hugo convert toJSON rewrites every content file's front matter, so this shows the backup and preview steps before you commit to it. It changes the front matter at the start of content files to JSON. This guide previews that change in a separate directory, checks the result, and only then replaces the originals. The commands were checked with Hugo 0.123.7 on Linux.

What you need

• A Hugo project with a configuration file such as hugo.yaml, hugo.toml or hugo.json.
• A writable temporary or working directory with enough space for a second copy of the content.
• A shell and the hugo executable. Check the installed version with hugo version.

Allow about five minutes for a small site. The conversion itself is quick; reviewing the generated files is the part worth doing carefully. You do not need root privileges for a project you own. Use elevated privileges only if the project is deliberately stored somewhere your account cannot write, and do not use sudo to hide a permissions problem.

1. Record the project and make a backup

Move to the project root, where Hugo normally finds the configuration and content directory.

cd /path/to/my-hugo-site
hugo version
tar -czf /path/to/my-hugo-site-before-front-matter-json.tar.gz content

Replace /path/to/my-hugo-site with the real project path. The archive is your recovery point. If the content is already tracked by Git, record the current commit as well:

git status --short
git rev-parse --show-toplevel

Expected version output identifies the release and platform, for example:

hugo v0.123.7+extended linux/amd64

2. Preview into another directory

The command reads content from the project and can write converted files below a separate output path. This is the safest first run because it leaves the source tree unchanged.

cd /path/to/my-hugo-site
preview_dir=$(mktemp -d /tmp/hugo-json-preview-XXXXXX)
hugo convert toJSON --output "$preview_dir"
find "$preview_dir/content" -type f -print

Hugo reports the number of files it processed. The output directory mirrors the relevant content paths, so a source file such as content/posts/example.md appears as $preview_dir/content/posts/example.md. Inspect a representative sample rather than assuming every file has the same front matter.

sed -n '1,24p' "$preview_dir/content/posts/example.md"

A converted file starts with a JSON object and then keeps the body below it:

{
   "draft": false,
   "tags": [
      "linux",
      "hugo"
   ],
   "title": "Example post"
}

The existing Markdown body remains here.

Hugo reformats the front matter and serialises values such as dates as JSON strings. The command converts front matter; it does not rewrite the Markdown body or rename the content files.

3. Compare before accepting the result

Compare the source and preview trees. The comparison should show front matter changes in the expected content files, not unrelated templates, configuration or generated output.

diff -ruN --exclude=.hugo_build.lock content "$preview_dir/content"

find content -type f -print | head -n 20
find "$preview_dir/content" -type f -print | head -n 20

If your project has a normal build check, run it against a disposable copy after reviewing the diff. A content-only review is still useful when the project has unrelated build dependencies.

4. Choose how to apply it

For a real migration, replace the originals only after the preview and comparison are satisfactory. Keep the backup until the site has built and the changes have been reviewed.

If the project is under Git, copy the preview files over the project and review the diff. This changes files in the working tree but does not commit or publish anything.

cp -a "$preview_dir/content/." content/
git diff -- content/

There is also an in-place mode. Hugo protects against this by refusing the operation unless you explicitly pass --unsafe:

hugo convert toJSON --unsafe

Common traps and recovery

Confusing output with destination

The command exposes both --output and the inherited --destination option. For this conversion, use the documented --output path when creating a separate preview. Do not assume a destination path is a backup unless you have inspected it.

Changing the wrong project

Hugo resolves the project from the current directory unless you provide a source path. Print the path before running a write operation:

pwd
find . -maxdepth 2 -type d -name content -print

If you used --source, verify that it names the intended project. The command's description says it converts all front matter in the content directory, so a broad source path can affect more files than a single post.

Undoing a bad conversion

With Git, discard only the conversion changes after checking the diff:

git diff -- content/
git restore --source=HEAD -- content/

mkdir /tmp/hugo-content-recovery
tar -xzf /path/to/my-hugo-site-before-front-matter-json.tar.gz -C /tmp/hugo-content-recovery
diff -ruN content /tmp/hugo-content-recovery/content