Fixing Hugo Multilingual URLs That Skip the Section Folder

If you’re building a multilingual Hugo site and notice your URLs are missing the section directory (for example, /wellness/), the most common cause is a front matter override using url. Here’s how to diagnose it quickly and fix it cleanly, without changing your site-wide config.

What went wrong

• Symptom: A file stored at content/wellness/… renders at /better-sleep-habits/ and /ja/better-sleep-habits/ instead of /wellness/better-sleep-habits/ and /ja/wellness/better-sleep-habits/.
• Root cause: The front matter url field hard-sets the output path, bypassing section-based routing. In multilingual mode, Hugo simply prefixes the non-default language (e.g., /ja/) to that forced path, so the section disappears in all languages.

The quick fix

• Replace url with slug in the front matter. slug controls only the final path segment and preserves the section and any permalink patterns.

Before (problematic):
+++
title = “Better Sleep Habits”
url = “better-sleep-habits”
date = 2025-07-31T13:24:09+01:00
+++

After (fixed):
+++
title = “Better Sleep Habits”
slug = “better-sleep-habits”
date = 2025-07-31T13:24:09+01:00
+++

Results:

• English: /wellness/better-sleep-habits/
• Japanese: /ja/wellness/better-sleep-habits/

Why slug works, but url doesn’t

• url fully overrides Hugo’s computed path. It ignores the content folder, section name, and most permalink rules.
• slug only replaces the last segment of the URL. Hugo still builds the rest of the path from the section and permalink configuration (or defaults).

Multilingual setup that “just works”

• File naming: Keep translations side by side with language suffixes:
  • content/wellness/better-sleep-habits.md (English)
  • content/wellness/better-sleep-habits.ja.md (Japanese)
• Language config: Define languages in your config; Hugo automatically adds /ja/ for the Japanese version. You don’t add language codes to slug or url.
• Translation linkage: If filenames differ or you’ve moved files, set the same translationKey in both front matters to keep them linked.

Permalinks: keep or customize the section

• Default behavior (no config): Hugo includes the section based on the folder path.
• If you do customize permalinks, make sure the pattern includes the section segment:
  [permalinks]
  wellness = “/:section/:slug/”
• Avoid patterns that intentionally remove the section if you want it visible. If you never set a permalinks rule, you’re fine—the default preserves the section.

Common gotchas to avoid

• url in front matter: Don’t use it unless you truly need a hard, root-relative path. Prefer slug.
• Static shadowing: A file under static/ with the same path (e.g., static/better-sleep-habits.html) will overshadow the rendered page. Keep content in content/.
• Ugly URLs: uglyURLs = true changes /slug/ to /slug.html. If you ever see .md in the served path, that’s typically a static file being served, not a rendered page.
• Localizing section paths: If you want the section directory itself localized, use per-language permalinks or a localized _index.ja.md for the section. Don’t insert /ja/ into slugs.

A simple, robust pattern

• Content files:
  • content/wellness/better-sleep-habits.md
  • content/wellness/better-sleep-habits.ja.md
• Front matter (English):
  +++
  title = “Better Sleep Habits”
  slug = “better-sleep-habits”
  date = 2025-07-31
  +++
• Front matter (Japanese):
  +++
  title = “良い睡眠習慣”
  slug = “better-sleep-habits”
  date = 2025-07-31
  +++

Takeaway

• If your multilingual page is skipping the section, check for url in the front matter first. Switching to slug restores the expected URLs (including the section) in all languages. Hugo will handle the /ja/ prefix automatically, no need to touch your TOML if you’re happy with defaults.