This website is built with Hugo and deployed on Github. To publish a new article, I only need to edit the Markdown file and upload it to Github, where GitHub Actions automatically generates the webpage for me. The entire process is so simple that I can update blog posts even from my phone.

As the number of blog posts increased, managing Markdown files became a challenge. Previously, without good organizational habits, I placed all files directly in the post/ directory. Later, as files accumulated, I created subdirectories like post/2024/ within the post/ directory. The URL of a blog post is related to its file location. For example, a blog post at post/2024/example.md would have the URL /post/2024/example/. To avoid changing the URLs of published posts, I left the old Markdown files in their original locations.

my blog old post structure

Multilingual Sites

Hugo has supported multilingual sites for many years, and I had considered creating an English version of my site, but translation was always an issue. With the advancement of AI in recent years, translation quality has improved significantly. Recently, I had the idea to create a multilingual site.

In Hugo, for multilingual sites, if you want a blog post to have multiple language versions, you typically need to create corresponding language versions of the md file. For example, the English version of blog.md would be blog.en.md, and other languages follow the same pattern.

Without a proper organization scheme, as time goes by, the number of files in the post/ directory would keep increasing, making it increasingly difficult to manage. Additionally, modifying blog post URLs would become more complicated in the future.

Therefore, it’s essential to address how to organize files in the post/ directory early on.

Need for a Proper Organization Scheme

Based on my past experience, creating a new folder for each year like post/2022/, post/2023/, post/2024/, etc., is generally sufficient for my needs.

For multilingual sites, placing all blog.md and blog.language.md files in one folder isn’t ideal for management.

It’s better to keep all language versions of the same blog post in one folder, such as post/2024/blog/blog.md, post/2024/blog/blog.language.md, etc. However, this would result in URLs like /post/2024/blog/blog, which is redundant. To address this, Hugo provides a slug parameter that can modify the final part of the URL path.

Also, to facilitate sorting, I add dates to the beginning of folder names.

For example, this article’s directory structure looks like this:

post
    ├───2017
    ├───2018
    ├───2019
    ├───2020
    ├───2021
    ├───2022
    ├───2023
    └───2024
        ├───20240920-jane-theme-v3-major-update
        └───20241105-hugo-multilingual-blog-structure
                    hugo-multilingual-blog-structure.en.md
                    hugo-multilingual-blog-structure.md

The Front Matter structure of this article looks like this:

---
title: Hugo 多语言博客搭建，如何优雅地管理多语言 Markdown 内容
date: 2024-11-05T11:04:39+08:00
draft: true
tags:
  - Hugo
  - 多语言
  - 博客搭建
  - 网站优化
  - 文件管理
  - URL 结构
  - 内容管理
  - 站点迁移
categories:
  - 计算机
lastmod: 2024-11-05T11:04:39+08:00
slug: ../hugo-multilingual-blog-structure/
summary: 本文介绍使用 Hugo 搭建多语言站点后的文件组织方案、URL 结构优化，以及如何安全迁移现有博客内容。适合想要构建多语言博客的 Hugo 用户参考。
---

Organizing Old Markdown Files

With a proper organization scheme in place, we should reorganize existing files and place them in appropriate locations. It’s particularly important to avoid URL changes. Hugo provides a url parameter that can set URLs to fixed values.

Here’s my process:

Step 1: Delete the public/ directory, generate a new public/ based on existing blog posts, and rename it to public_old/.

Step 2: Transfer files one by one, adding the original url address to transferred files.

Step 3: After completing the transfer, regenerate the public/ directory.

Step 4: Compare public/sitemap.xml and public_old/sitemap.xml to check if URLs are consistent.

Step 5: Use Beyond Compare to check if public/ and public_old/ are consistent.

When manually modifying URLs, also pay attention to URL case sensitivity.

References