Skip to content

Migration from jekyll to astro

Published: at 04:11 PM

Table of contents

Open Table of contents


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.


I have a bunch of markdown blog post files, an, 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 -- --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/ 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:


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:

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.