How I Built this Blog Using Hexo, Cloudflare Pages, and More

A very brief record on how to build and customize a Hexo blog, migrate from WordPress, and deploy it on Cloudflare Pages.

I first started my blog in 2020 using Hugo. Then I decided to migrate everything to self-hosted WordPress because I liked the idea that I could edit my posts in the browser (and therefore on mobile devices). Today I again migrated everything to this new site built with Hexo, as I realized that I never really need to edit posts in the browser, and I think I should make the best of what Cloudflare Pages offers for free. I didn’t return to Hugo because 1) I’m not a Go programmer, 2) I’m don’t care about what Hugo brags about itself, which is its building speed, because it doesn’t really make any difference for a site of less than 100 posts, and 3) I have built some Hexo sites elsewhere before.

Installing Hexo and the theme

Installing Hexo is simple. I went to its documentation, installed, and set up. Then I added site configurations to my _config.yml.

The next step is to find a nice-looking theme. If you’re doing the same, keep in mind what you need for your site, e.g.

Support for tags/categories,
Site-wide search,
RSS feed generator,
Comment sections,
Support for $\LaTeX$,
Syntax highlighting,
View counts and other analytics.

Though it’s always possible to add the missing parts to an existing theme, it certainly helps if you can find one that fits your needs.

I ended up with Suka because I like its simple design style and its rich support for extensions. (It is apparently developed by Chinese developers, and part of its documentation has not been translated into English.)

I installed the theme by following this page and configured the theme by following this page.

Customizing the theme

The first step was to initialize a Git repository in the site folder:

git init

I removed _config.yml from themes/suka/.gitignore so that my edits could be tracked.

I installed gulp-cli for Suka, as described here.

Fonts

I replaced the default font with Catamaran, and Noto Sans Simplified Chinese for Chinese. I copied the snippet generated by Google Fonts

1
2
3

<style>
@import url('https://fonts.googleapis.com/css2?family=Catamaran&family=Noto+Sans+SC&display=swap');
</style>

to <head> in themes/suka/layout/_partial/head/index.ejs, and added

1
2
3

body {
    font-family: Catamaran,'Noto Sans SC',system-ui,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",sans-serif;
}

to themes/suka/src/css/style.css.

Then I run gulp build in themes/suka for the changes to take effect.

MathJax

I added this snippet to <head>:

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async
        src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
</script>
<script>
    window.MathJax = {
        tex: {
            inlineMath: [['$', '$'], ['\\(', '\\)']]
        }
    };
</script>

If you don’t use inline math, remove the last <script>.

Custom Styles

I didn’t like box shadowing so I removed all of them in themes/suka/src/css/style.css and replaced some with dotted borders:

1	border: 1px dotted rgba(0, 0, 0, .1);

I removed avatar from article previews, and darkened the color of hyper links.

There might also be other tweaks here and there.

Again, remember to run gulp generate.

Pages

I added pages for tags and “about” by following this page.

RSS

To use RSS I needed to

1	yarn add hexo-generator-feed

in themes/suka, and then I enabled it in the config file.

Migration from WordPress to Hexo

I followed this page.

But there were some problems with the migration.

All the tables broke down in the generated Markdown files.
Paragraphs were not separated.
A { followed by a # anywhere in the posts would cause Hexo to crash.
Some maths formulas were not correctly converted.

I fixed the problems… sort of manually.

Deploying on Cloudflare Pages

I followed this page.

I pushed the whole repo to GitHub. Then I went to Cloudflare Pages and I thought the remaining steps should be easy. Well, it was not as easy as I expected.

After a few failures, I realized the theme Suka needs NODE_VERSION to be set to 14 in environment variables. Also the command should be

1	cd themes/suka && yarn install && cd ../.. && hexo generate

Then I bound the page to my own domain.

Done!