Deploying MoleLab with Hugo, Blowfish, GitHub, and Cloudflare Pages

The first version of MoleLab is a deliberately simple static blog. Hugo generates the site, Blowfish provides the theme, GitHub stores the source, and Cloudflare Pages builds and serves the final HTML.

This post records how the site was put together and what to keep in mind when maintaining it later.

Why this stack

#

Hugo is fast, simple, and produces a fully static site. A personal blog does not need a database, login system, or server-side runtime, so static output is a good fit.

Blowfish is a polished Hugo theme with dark mode, search, multilingual support, article lists, and comfortable typography. MoleLab currently uses its background homepage layout.

GitHub keeps the source code and history. Cloudflare Pages connects to GitHub, builds the site on every push to main, and handles hosting and HTTPS.

Local setup

#

Install the extended edition of Hugo first. My local build uses:

hugo version

Then initialize the site:

hugo new site . --force
git init -b main

The theme is managed as a Git submodule:

git submodule add https://github.com/nunocoracao/blowfish.git themes/blowfish

At the moment, the submodule tracks Blowfish’s upstream hugo-new-version branch so Hugo 0.163.1 builds without compatibility warnings. Once Blowfish publishes a release containing that compatibility metadata, the submodule can move back to a release tag.

Multilingual configuration

#

MoleLab is bilingual. Chinese is the default language and is served at the root:

https://molelab.dev/

English is served at:

https://molelab.dev/en/

The core configuration is:

baseURL = "https://molelab.dev/"
defaultContentLanguage = "zh-cn"
defaultContentLanguageInSubdir = false
disableDefaultLanguageRedirect = true

Chinese content lives in content/zh-cn, and English content lives in content/en. When the translated versions share the same path, Hugo and Blowfish can link them through the language switcher.

Pushing to GitHub

#

After the initial setup, commit and push the source:

git add .
git commit -m "Initialize bilingual Hugo Blowfish blog"
git remote add origin https://github.com/molefool/hugo.git
git push -u origin main

Daily updates use the normal Git flow: edit locally, build locally, commit, and push.

Cloudflare Pages settings

#

After connecting Cloudflare Pages to the GitHub repository, use main as the production branch.

Build command:

git submodule update --init --recursive && hugo --minify -b https://molelab.dev/

Build output directory:

public

Environment variables:

HUGO_VERSION = 0.163.1
HUGO_ENV = production

The -b https://molelab.dev/ flag matters. It makes canonical URLs, RSS feeds, sitemaps, and multilingual links point to the real domain instead of the temporary pages.dev domain.

Custom domain

#

Once the first deployment succeeds, open the Cloudflare Pages project and add molelab.dev under Custom domains.

If the domain’s DNS is also managed by Cloudflare, Cloudflare can create the required records and certificate automatically. When the domain becomes active, https://molelab.dev/ will serve the Pages deployment.

Common pitfalls

#

The first pitfall is the theme submodule. Cloudflare must fetch the theme during the build, so the build command needs:

git submodule update --init --recursive

The second pitfall is the Hugo version. Hugo moves quickly, and themes can lag slightly behind. Before pushing, run:

hugo --gc --minify

The third pitfall is baseURL. Once the final domain is known, both the local config and the Cloudflare build command should use that same domain.

Improving access speed from mainland China

#

MoleLab currently uses the free Cloudflare Pages plan. That gives us a simple workflow, free hosting, HTTPS, global edge locations, and automatic deployments. It does not guarantee stable access from mainland China, and it is not the same as using a domestic CDN.

The lightweight free optimizations come first:

• Keep the site static and avoid heavy client-side frameworks.
• Compress images before publishing them.
• Use long cache lifetimes for CSS, JavaScript, and images, while keeping HTML fresher.
• Enable Cloudflare’s free performance features such as Brotli, HTTP/3, and Early Hints.
• Use the final baseURL so resources and canonical links do not point to temporary domains.

These steps reduce bytes and requests, but they do not solve every network path issue. If MoleLab later needs consistently fast access from mainland China, the more reliable path usually involves ICP filing and a domestic cloud/CDN provider. A middle path would be keeping Cloudflare Pages as the main deployment while adding a mainland-friendly static mirror, such as object storage plus CDN, or another static hosting platform with better mainland connectivity.

For now, I will keep the free Cloudflare Pages setup, improve the content and structure first, and only add a mainland mirror when traffic data shows that it is worth the extra work.