I’ve been using the Hugo Stack theme for a long time to write my blog. It’s a great theme, but I think it’s better suited for blogs with a lot of images. My current website has accumulated over 1,700 photos, and with the Stack theme, generating the site produces an additional 7,000 to 8,000 files! This makes the entire repository very large, making it difficult to deploy on third-party free platforms like Cloudflare Pages.

The problem is clear: I need to switch to a lighter theme, preferably one focused on text. So, I searched through the Hugo themes site and finally settled on a theme called Bear. After downloading it, I found it truly lightweight—only a few dozen KB—and easy to customize. It comes with no CSS at all, just the basic HTML structure. However, when I started using it, I realized I needed to add some CSS, so I tweaked the theme a bit. Later, I discovered that the official theme library has multiple versions of Bear, and Bear Cub includes CSS, so I switched to that one.

The most challenging part of migrating to this new theme was the file structure of my original Hugo project.

All my content is stored under the content directory in the project. But within that, I split it into two folders: one called post and another called posts (just “post” with an “s”). The main reason for this split is that there are simply too many articles. If they were all in one folder, it would be easy to accidentally copy files to the wrong place while writing or organizing. My strategy is to keep “archived” historical articles in one folder (like posts) and place newly written articles in another (like post). Once the post folder accumulates a certain number of articles, I manually move them into the posts folder for archiving. This approach feels clearer and more manageable, reducing the chance of errors.

Another characteristic of my setup is that each blog post’s Markdown file and its associated images are stored in the same folder. For example, if I write an article called “Cat,” the path might be /content/posts/cat/, containing index.md, index.en.md (since my blog is bilingual), and all the images used in the article (e.g., cat1.jpg).

I personally consider this approach an advantage:

1. Super convenient for local writing: When inserting images, I can just paste them directly into the article folder.
2. Easy to preview and manage: With images right next to the Markdown file, any previewer that supports local images can display them instantly.
3. Minimal risk of losing images: The paths are simple and fixed, keeping files and images bundled together.

But this became a problem when switching themes! Because most popular themes default to a “text and images separated” model—Markdown files under content/... and images in a unified directory like static/images/. This might be for cleaner repository management or cache optimization, but I still find my “images in the same directory” method more convenient. So, the biggest challenge in switching themes was: How can I make my existing “images in the same directory” file structure fully compatible with the new theme’s requirements?

The adaptation process… naturally involved a lot of trial and error. The solution I eventually settled on was: Turning my core blog article folders (the post/posts directories under content) into a Git Submodule.

Here’s how I did it:

1. I separated the folders containing all article content into an independent Git repository (let’s call it the “writing repository”).
2. Then, in the theme repositories (both the original Stack repository and the new Bear theme repository), I included this independent “writing repository” as a Git Submodule.

The benefits of this approach are:

• Simplified writing: To write new blog posts or add images, I only need to work within this independent “writing repository,” maintaining my preferred path structure (images and text in the same directory).
• Flexible theme adaptation: Now, I’m using two themes simultaneously! The original Stack repository uses this content submodule, and the new Bear repository also uses it. This way, I only need to update the “writing repository” once, then build the repositories for both the Stack and Bear themes separately to generate static site files adapted to each theme.
• Easy integration with image galleries: I’ve already synced the writing repository to Cloudflare R2 storage. If needed, I can switch the entire image setup to remote links to avoid quickly exhausting resources on free services like Vercel.
• To handle automated builds for both theme repositories, I added several workflows to GitHub Actions configurations, ensuring that updates to the writing repository automatically trigger builds and deployments for both theme repositories.

Choosing this “dual themes + content submodule” approach wasn’t just about technical adaptation; there’s also a practical reason: My current Alibaba Cloud VPS is about to expire. Right now, the blog is primarily hosted on the VPS, which is relatively stable and fast. But for the long term, I’m likely to move the entire site to platforms like Vercel or Cloudflare Pages. To migrate all the content there, the site’s size needs to be as optimized as possible. Choosing the super-lightweight Bear theme is largely in preparation for this future deployment strategy.