Migration from jekyll to astro

Table of contents

Motivation

I have been using jekyll for quite some time and I’m quite happy with it. I first know astro during one of the all hand meetings and it looks interesting to me, so I decided to give it a try and migrate my posts to astro + cloudflare pages.

Preparation

I have a bunch of markdown blog post files, an about.md, as well as associated asset files in public/files/*. Since my blog does not have any dynamic requirements so using astro as a static site generator is fine. I decided to use astro-paper theme, so first step is to init the project root:

npm create astro@latest mxcao.me -- --template satnaing/astro-paper

After a series of prompts, we should have the template repo ready to go. Remember to install the dependencies npm i.

Now try npm run dev and play around, make sure there’s no errors with the currently clean start.

I fiddled with npm dependencies a bit and had to revert my changes back to the template default package.json and package-lock.json. The only addition I made then is npm install wrangler --save-dev.

To ease our deployment later, add "deploy": "astro build && wrangler pages deploy ./dist", to package.json scripts.

Site config

Next step is to personalize the site to make it more personal, follow the guide How to configure AstroPaper theme and adjust the file src/config.ts .

I also edited src/pages/index.astro to update the home page message, making it more succint and relevant.

Updating src/pages/about.md is quite straightforward, just need to get rid of unrelevant frontmatters from jekyll like layout: page.

Migrate posts

Now comes to the meat: migrate all my blog posts to astro and make adjustments to the files.

Notably this includes:

• Adjusting frontmatters: there’re a few required fields we need to include, e.g. description, pubDatetime, etc, and adjust tags to yaml list format
• Fix broken links: luckily this can be achieved via VSCode search & replace, search with regex \{% link public\/files\/(.+?) %\} and replace with @assets/files/$1
• Adjust file names: my jekyll blog post files begin with a date string like 2023-03-03-, to batch rename, I use this bash command for file in *.md; do mv "$file" "${file:11}"; done

Deploy

I chose to deploy all my blog posts to Cloudflare Pages rather than doing GitHub syncs. The benefits of such transition is I can now rely on Cloudflare dashboard to view the analytics without self-hosting my own umami instance. Of course, this also comes with added benefits of performance optimizations and easy management.

Create file wrangler.toml with the following content:

name = "mxcao-me"
compatibility_date = "2024-03-29"

and then do npm run deploy to deploy dist files to production.

I personally don’t want to expose the preview domains, so I followed the following docs to set up redirects:

• Redirect *.pages.dev to a custom domain
• Redirecting www to domain apex
• ​​Enable Access on your *.pages.dev domain
  • Note that for the access policy, I kept the wildcard * so that only the preview domain is protected by access.

The first deployment may take some time to propagate to the RoW (Rest of World), wait a few mins (grab a cup of coffee) and check again.

Set up VSCode

I use VSCode to create new posts, so it worth the efforts to set up necessary hooks. Notably, follow How to use Git Hooks to set Created and Modified Dates to automate the modDatetime updates.

To use the supplied snippets when creating new posts, I have to update my keyboard shortcut to trigger suggestions, since the default Ctrl+Space is already used in other places.

Open the keyboard shortcut pane (Cmd+k, then followed by Cmd+s), search for trigger suggest. Make changes as you wish. For me it’s Option+Space.

Now when creating a new post, type template followed by Opt+Space to init the post, then Opt+Space again for the nested frontmatter snippet.