Recently, while using Hugo to generate a static site, I encountered a rather puzzling issue with multilingual content. I had a Chinese article (index.zh-cn.md) where I had properly set the front matter with draft = false and a current publication date. However, during development with the standard command hugo server, the images attached to the article wasn’t loading:

After exhaustively investigating the problem—checking various configurations and paths, I discovered that no corresponding resources were being generated in the public folder for that article. Finally, in a moment of experimentation, I ran the server with the draft flag by executing hugo server -D, and the images rendered correctly.

On further inspection, I realized that the English version (index.en.md) of the article was still set as draft (draft = true). Since Hugo treats all language versions of a content piece as a single content collection, if any version remains a draft, Hugo considers the entire group as unpublished. In other words, even if your Chinese content is properly set to draft = false, the presence of an English draft causes Hugo to skip generating associated resources (like images) when not running with -D.

Below are a few key takeaways from this troubleshooting experience:

1. Hugo treats multilingual pages as a single content bundle.
   When Markdown files for the same content but in different languages exist in the same bundle or directory, if any one version is flagged as a draft, it affects the overall publication status. Therefore, even if your Chinese version has draft = false, the English version remaining at draft = true can cause Hugo to consider the whole set as incomplete, and thus it won’t compile the resources in the normal build mode.

2. The –D flag is only recommended for local testing, and it’s important to understand the implications of draft and future settings before the final deployment.
   It’s common during development to use “hugo server -D” which builds all drafts, future posts, and other excluded content. While this is convenient for testing, once you switch to the regular build mode (or deploy to production), any content still marked as draft (or dated in the future) will be omitted. Relying solely on -D can make you overlook a draft status in one language or a higher-level configuration that might hide additional drafts.

3. Ensure consistency in the front matter across all language versions.
   It’s not just the draft flag; other parameters like date, slug, and so on—if they vary significantly between language versions—can cause conflicts in Hugo’s multilingual processing logic. Maintaining consistent or appropriately aligned front matter is key to ensuring that the multilingual site operates as expected.

4. Use command-line tools and review configuration files for debugging.
   If you suspect an article is not being compiled properly, run commands such as:
      • hugo list drafts – to list which files are still marked as drafts;
      • hugo list future – to list posts scheduled for future publication;
      • hugo list expired – to list posts that are considered expired.
   After confirming that drafts and future dates aren’t the issue, also take a look at your theme or global configuration settings such as buildDrafts, buildFuture, enableDraft, and enableFuture. Additionally, check for any potential overrides in _index.md, cascade configurations, or similar files.

5. Embrace the lessons learned and enjoy the process of configuring multilingual sites.
   The beauty of multilingual sites is their ability to reach a global audience, but Hugo requires careful handling of the front matter for each language version. Choose an appropriate directory structure, bundle approach, and cascading configuration to ensure a smooth and predictable multilingual publication process.

In summary, this incident proved that:
  • When working with multilingual content, ensure that flags like draft and date are consistent or meet your expectations in every language version.
  • A misconfigured draft setting in any one language can prevent the entire content set from being published correctly.
  • Relying on the -D option to bypass issues can mask underlying configuration problems—using command-line tools and reviewing your setup is the right way to address these issues.

I hope this experience serves as a helpful reminder for all of you. Feel free to share your own Hugo multilingual mishaps in the comments, so that together we can build static websites that are both stable and controllable!

Happy blogging!