Three Requirements, One Moment#

There were three motives for this migration: one push and two pulls.

The push: I didn’t want to keep patching minima. The next section unpacks the bill, so here’s just the conclusion. Over two years, every customization to the blog was pasted into the body as an include, and each layer of patches made the next one more expensive. The expected cost of “adding something to the blog” had overtaken the cost of “rewriting it.”

Pull one: I needed a landing page. The blog index can’t do that job. It only lists posts in reverse chronological order, and what I wanted was an entrance I could arrange freely: what I’ve written lately, what I’ve built, what I’m doing now. Implementing that in minima would mean forking the theme’s home layout first, then pasting five more layers of patches on top.

Pull two was multilingual content. Content sites are static by default, but my blog is bilingual, and “bilingual” has a very specific meaning for me: when a recruiter clicks through from my résumé while I’m looking for a co-op, they cannot land on a screenful of Chinese write-up. That requirement splits in half. One half is that the content needs Chinese and English versions. Jekyll has plugins that can do this, but Jekyll hosted on GitHub Pages only runs whitelisted plugins, and the multilingual ones aren’t on the list. Using them means building locally and pushing the output, which is moving CI’s work back onto my own machine and back to the same old toolchain bill. The other half is filtering and switching content by the visitor’s language. That’s a runtime decision, and purely static hosting was never born with that organ; the only way to add it is another <script> pasted into the body, the same disease of patch debt. How it landed is in section 3.

There’s also a cost that isn’t a motive but has been accruing interest the whole time: Ruby isn’t part of my toolchain. Every time I came back to this project, the opening act was bundle install, followed by some gem version problem, some strange PATH problem — and I was debugging in a language I don’t write, with a package manager I don’t know. Jekyll itself isn’t slow. What’s slow is the ticket price every time I walk in.

The direction was settled long before. When I wrote the htmx post, I spent a whole section on islands architecture and said Astro makes it a first-class citizen: zero JS by default, and only the components that need a runtime get one. A blog that is “content first, interaction on demand,” a landing page that is “fully free-form, cut to fit,” and a multilingual mechanism that is “static at the base, dynamic in patches” — three requirements pointing at the same framework. Any one of them alone would have produced a different answer. For the landing page alone, I could spin up a new repo and throw anything together. To escape minima alone, I could switch to another theme and keep going with Jekyll. For multilingual content alone, I could grit my teeth and build locally before pushing the output. But all three colliding at once made “one monorepo, one Astro setup, two kinds of output” the only reasonable shape.

What I Hacked into minima#

1
{% include override-styles.html %}
2
{% include load-barlow-font.html %}

1
{% include override-styles.html %}
2
{% include load-barlow-font.html %}
3
{% include math-support.html %}
4
{% include mermaid-support.html %}

1
*:not(code, .katex *) { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; }
2
code, span:is(.highlight *) { /* … */ background-color: #f0f0f0 !important; }

1
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.18.6/dist/katex.min.js"
2
    integrity="sha384-7jGyG5zFwmEamqNWdCbpsPn+GTWEis3lnV7X/jXHyhFpJG7ExABLyMapabg8F4+p"
3
    crossorigin="anonymous"></script>
4
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.18.6/dist/contrib/auto-render.min.js" ...
5
    onload="renderMathInElement(document.body, { delimiters: [/* … */], throwOnError: false });"></script>

1
mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
2
mermaid.run({ querySelector: 'code.language-mermaid' });

1
{% include center-figure.html src="/assets/2025-08-07-a-brief-introduction-on-impedance/Low_pass_filter.png"
2
    alt="LC Circuit" maxw="400px" maxh="400px" %}

Why Astro and Fuwari#

There were three criteria for the migration, ordered by importance.

First, one tool had to answer all three requirements at once. The blog needs a content pipeline: content collections turn markdown into data with a schema, a remark/rehype plugin chain handles rendering, and RSS, sitemap, and reading time all have ready-made shapes. The landing page needs a free frontend: routing, components, and styles all under my control. Multilingual needs a third thing: pages generated statically, with the dynamic bits shrinking into a few isolated components. Astro happens to give all three.

Second, JS granularity has to reach the component level. The vast majority of the blog’s content is static, but a few components always need to be alive — the two language switchers are the live ones; the landing page has zero lines of client JS, and that’s all it needs. Astro’s default is exactly “no JS unless you ask for it.” The full version of that argument is in section 7 of the htmx post, so I won’t repeat it here.

Third, the toolchain has to be mine. npm, TypeScript, Vite — that’s the stack I debug in daily, and when the build fails I can read every line of the error. That sounds obvious, but on the Jekyll side it was a wound that kept bleeding for two years.

The rejected options, briefly. Hugo is another patient with the same disease: a theme model, templates living elsewhere, customization by overriding, multilingual still assembled from plugins — only the template language changes from Liquid to Go templates. Next is heavy in the opposite direction: bringing a runtime and deployment assumptions to a mostly static site, in exchange for capabilities I would never use.

But this blog wasn’t written from scratch. It started from Fuwari, an Astro blog theme — or more precisely, material. I should be clear about the difference between “forking a theme” here and the “theme model” I spent a couple thousand words trashing in section 2.

The difference is where the code lives. minima’s templates sit in a gem, and all I can do is override and inject. Fuwari’s entire src/ sits in my repo, including the theme mechanism itself: the remark plugin that handles mermaid, the plugin that computes excerpts and reading time, the rehype components that render cards — all named, diffable, editable files under src/plugins/. The day I forked it, the theme’s maintainer became me. That’s exactly the “ownership of the fork” from section 2 — except this time I took it.

What I’ve touched since taking over is roughly a list of plugins: fenced code blocks for mermaid become <pre class="mermaid-src"> at build time and are handed to the frontend; remark-excerpt and remark-reading-time generate excerpts and durations for list pages; GitHub cards, link cards, and admonitions go through rehype-components; code blocks were switched to expressive-code, with fonts and colors adjusted. None of this is “configuring a theme”; all of it is writing my own build pipeline.

1
<div id="toc-card" class="hidden lg:block sticky top-4 mt-4">
2
    <WidgetLayout id="toc-widget" ...>
3
        <div id="toc-inner-wrapper" class="max-h-[calc(100vh-12rem)] overflow-y-auto ...">
4
            <TOC headings={headings} />

1
const mermaidRuntime = (window as unknown as { __mermaidRuntime?: MermaidRuntime })
2
  .__mermaidRuntime ??= { mounted: false, queue: Promise.resolve() };
3

4
function scheduleMermaidRender(): void {
5
  mermaidRuntime.queue = mermaidRuntime.queue.then(renderMermaid);
6
}

One Repo, Two Projects, Three Domains#

Choosing the framework was the easiest part of this migration. The hard part was deployment. Why it was hard starts with one small feature on the landing page.

The landing page has a “recent posts” list. Its simplest implementation is build-time generation: a script reads every post’s frontmatter in posts, drops drafts, filters by tag, picks the English version of each Chinese/English pair, takes the five most recent by publish date, and writes out JSON. It’s wired into the landing page’s dev and build commands, re-syncing on every build:

1
"dev": "node scripts/sync-posts.mjs && astro dev",
2
"build": "node scripts/sync-posts.mjs && astro build",

Build-time coupling is good coupling: the output is purely static, with no runtime fetch, no CORS, no loading state, and the list updates on the same day as the blog. But it comes with one hard constraint: the landing page’s build must be able to read the blog’s source files. Two sites, one repo, no other option. That’s where the monorepo came from.

And that knocked GitHub Pages out. Its publishing model is one repository per site: one publish source, one custom domain. The requirement for two projects, each with its own domain, has no counterpart in that model.

I considered every alternative I could think of:

• Two repos, with the landing page checking out the blog at build time. Cross-repo checkout needs a token, the build order becomes a coordination problem between two repos, and pushing a post to the blog won’t trigger a rebuild of the landing page, so the list stays stuck at the old state.
• The landing page fetching the blog’s RSS or JSON at runtime. That adds a loading state above the fold, ties the landing page’s availability to the blog’s availability forever, and contradicts the whole premise of “static output, JS on demand.”
• One site, with the blog under a path prefix. One site carrying two mental models, with the base path and CNAME to fiddle with, and the landing page and blog’s lifecycles bound together from then on.

Cloudflare Pages’ model happens to be shaped exactly like the requirement: one repo can host multiple projects, and each project specifies its own root directory, build command, and custom domain. So the topology now is:

flowchart LR
    P["push to main"]
    P --> W["Pages build trigger<br/>configured in the dashboard"]
    W --> L["project: landing<br/>root landing/"]
    W --> B["project: blog<br/>root blog/"]
    L --> A["ansonate.ink"]
    B --> D["blog.ansonate.ink"]
    G["GitHub Pages<br/>source docs/"] --> E["dev.ansonate.ink"]

The deployment chain got a new lead too. GitHub Actions in the repo only validates: astro check, then a build on Node 22 and another on Node 24, with no deploy step. The actual go-live happens on Cloudflare’s side: the Pages build trigger is configured in the dashboard rather than in the repo, and a push to main starts the build and deploy of the corresponding project. CI owns “is the code right”; CF owns “is the site alive.” The division of labor is clear, and the price is in section 6.

The division of domains:

The third domain deserves its own paragraph. Those dozen or so SPA demos are each their own repo, each with GitHub Pages enabled. GitHub has a handy mechanism: once a user site has a custom domain configured (with DNS pointed at GitHub Pages first), project sites under the same account hang off subpaths of that domain by default. So the user-site repo claims dev.ansonate.ink; every demo can live on as dev.ansonate.ink/<repo>/, and old links from the main site get 301’d there.

This Pages site publishes from docs/, which contains only a single redirect page with noindex. Strictly speaking it could hold nothing at all — the demos’ survival doesn’t depend on what’s at the root path — but the root path itself needs somewhere to land, otherwise anyone visiting dev.ansonate.ink directly hits a 404. Now that redirect page sends this small crowd to the gallery at ansonate.ink/apps. Nothing old died; it just moved house.

Wait! Old Links Must Not Die#

The completion criterion for a migration is that every old URL has somewhere to land, because I put the old links on my résumé. The old site was small, but it had plenty of URL types: eight posts, a feed, an about page, and a dozen demo paths.

Posts first. Jekyll’s default permalink is /:categories/:year/:month/:day/:title.html, so old post URLs look like this, and they’re long:

1
/mathematics/deep-learning/2026/10/16/desmos-and-calu.html

The categories were whatever I felt like, and some contain spaces (“Web Development” on the htmx post). The browser actually requests the %20-encoded form. Cloudflare Pages’ _redirects supports placeholders, so one rule matches both the decoded and the encoded form:

1
/:category/programming/2026/10/07/htmx-tailwind.html  https://blog.ansonate.ink/posts/htmx-tailwind/  301

There are two copies of _redirects, because rules apply per project: the apex project can’t see the blog’s rules, and vice versa. The apex copy (landing/public/_redirects) uses absolute URLs: old posts and the feed 301 across domains to the blogs subdomain, and demo paths 301 to the dev subdomain. The blog copy (blog/public/_redirects) uses site-relative paths, catching old links that hit the blog domain directly. The feed is a separate line: jekyll-feed produced /feed.xml, and on the Astro side it’s /rss.xml.

The demo paths are thirteen exact redirects plus two lowercase aliases — early repo names weren’t consistently cased, and both spellings have to be caught:

1
/resume-tailor/*  https://dev.ansonate.ink/resume-tailor/:splat  301
2
/credicheck/*     https://dev.ansonate.ink/CrediCheck/:splat     301

Think carefully before you use a 301: browsers and CDNs cache it long-term, so once you get one wrong, the time it takes the fix to take effect is out of your hands. The safe order is to start with 302s for a few days, confirm every destination is right, and only then switch to 301.

_redirects also has places it can’t reach: it only handles paths, not domains. A domain-level redirect like apps.ansonate.ink to ansonate.ink/apps has to be a Redirect Rule written in the Cloudflare dashboard. That’s recorded in the landing page’s README now, because I’ll almost certainly look in the wrong place next time.

Free Is Not Free#

This topology isn’t free. Here’s the bill.

Two build chains. GitHub Actions validates once, and Cloudflare builds again when deploying. The direct consequence is that green CI doesn’t mean it’s live: a build failure on the CF side only appears in a different dashboard, and nothing turns red on GitHub. Versions have to be aligned in three places too: engines in landing/package.json, the pnpm version hardcoded in the workflow, and the one in the CF project settings. Any drift between them means “works locally, passes CI, explodes in production.”

Two lockfiles, two sets of dependabot configs, DNS for the domains. _redirects is a table that needs maintenance, and site-level paths (the feed, the about page) have to be remembered and updated whenever the site is restructured. One thing is hard to place: the Pages project settings live in the Cloudflare dashboard, and that config is the only part of the setup that isn’t under version control. There isn’t much of it, but every time I want to say “all config is code,” I have to add a caveat.

When does this become over-engineering? If all you need is a blog, GitHub Pages with Jekyll or Hugo is still the least fuss, and the story ends there — right up until you start reshaping the publishing pipeline so another page can read the content.

Closing#

In that announcement post from 2024, I wrote that Jekyll fit my preferences perfectly. That was true at the time, and it isn’t exactly wrong now; the context just changed. Over two years my usage grew into the shape of a theme: a landing page, a set of reusable components, a bilingual convention — while the tool stayed where it was. Jekyll didn’t get worse. My demands on it changed.

The substance of this migration is that I stopped renting the presentation layer. From markdown to DNS, every layer now has a name, a version, and an error message I can read. The price is doing my own plumbing: two build chains, three domains, a redirect table, and a bit of Pages config hiding in a dashboard.

Publishing a post now goes like this: write it, push, both projects build, the landing page’s “recent posts” updates itself, and the old links stay where they are. Not a single step in that flow requires me to remember anything, which is probably what the person pasting includes into post bodies two years ago was after.

Appendix: Migration Checklist#

For anyone about to do the same thing, in order:

1. Inventory every URL on the old site first: posts, feed, about, attachments, demos. Put them in a table. Migration is done when that table is all green.
2. Order the criteria for choosing a framework: is the toolchain yours, JS granularity, ecosystem. Performance benchmarks come last.
3. Fork the theme; don’t hack the theme, unless you know there won’t be many new things later. There’s only one test: are the theme’s template files in your repo?
4. Content before styling: settle the frontmatter schema, where content collections live, and the multilingual conventions before you talk about how it looks.
5. Share content between sites with a build-time script — explicit and diffable. Don’t use runtime fetch.
6. Confirm your host supports “multiple projects per repo, built by directory.” That’s the prerequisite for the monorepo.
7. Separate validation from deployment: CI only validates, deployment is triggered by the host on push, but accept that “green light doesn’t mean live.”
8. Redirects: 302 first, 301 later. Use placeholders for old paths with spaces, and test both encoded forms.
9. Learn _redirects’ limits: it doesn’t handle domains, there’s a cap on rule count, and domain-level redirects go in the dashboard.