Migrating my blog from Pelican to Astro

Static site generators (aka SSG) is a web development technology that pre-renders web pages statically. It is not necessary to serve the web pages using an application server like Python or Node.js. (Some SSG supports SSR, server side rendering) There are many SSG. Hugo (Golang), Next.JS and Gatsby are some of the popular frameworks. In this article, I would like to explore about two SSG that I have used: Pelican and Astro.

Pelican is the first SSG that I used when setting up this blog. Pelican is a SSG that make use of templates to build HTML pages, just like Hugo and Jekyll. The template language is Jinja2. If the web developers need to create plugins, then he/she needs to write plugins that is Python based. There are lots of plugins for Pelican (this is the new one using namespace). (this is the old plugin repository) Many plugins are essential and very useful, such as creating a site map, searching (using Stork), supporting other markup format (AsciiDoc, Org Mode), WebAssets (minimizing CSS/JS), using data science to create a list of similar articles.

Pelican has a concrete concept of articles (e.g. web blogs), pages (e.g. the about page, privacy policy page, etc.), categories and tags. Here’s some of the advantage of Pelican:

So, Pelican is great but there is still short comings IMHO.

Astro is also a static site generator. Astro supports many major JavaScript frameworks, like Svelte, VueJS, React, Preact, SolidJS, AlpineJS, Lit and etc. Also, Astro supports multiple frameworks to co-exist in the same website.

I had been using Pelican for a while. I had investigated about using the Quasar framework with Pelican, but I found that it is not very good because there is no tree shaking (it needs to include a huge JavaScript UI framework for client browser). Besides that, by nature Pelican is not a JavaScript or Node.js platform, so the code for using Quasar is different from using it on Node.js. Next, I heard about Svelte and SvelteKit. It supports Markdown and there are very few examples for using it with AsciiDoc, so I did not spend much time on it.

OK, back to Astro. Astro was advertised in a number of places and caught my attention. Here is some of the advantages of Astro:

Here’s some of my views, suggestion and observations when migrating from Pelican to Astro:

Unlike Pelican, Astro does not provide a built-in data structure for the metadata of the list of articles and pages. In Pelican it is very easy to access the metadata. Besides that, in Pelican, suppose there is a main page template and a head template (HTML5 meta tag) template, the main page template includes or references another template. Inside the other template, I could overwrite a block (section of HTML codes) that was defined in the main template. I could also copy a block from the parent (main template), by calling {{ super() }}. That is handy.

As far as I know there is currently no such feature in Astro. It could be cumbersome when an article template includes a base template, and the base template includes another template. I am not aware of any easy method to overwrite or copy block from the grand-father or parent templates.

For the time being, I collected all the metadata of the articles and save it as a JSON file. Then in any Astro layouts or components, I could load the JSON file to access the metadata of the current article and neighbour article(s).

Previously, if I need to wrap a <table> with a <div> with Pelican, I was using a JavaScript to search for the table tag and wrap it. But it is being performed in client browser. In Astro, I am utilizing the rehype plugin to perform the same thing, but at build time. This makes less work to do in client side. Rehype is a HTML processor that could perform many things like HTML code sanitizing, minify CSS/JS, removing comments inside HTML, syntax highlighting and etc.

With Tailwind CSS, you can write something like this for dark mode support:

It is easier to understand and faster to write. Previously on Pelican, I need to use two separate CSS files for dark and light theme.

Astro natively supports Markdown. It also have a Pandoc plugin. But Pandoc is not as good as Docutils when converting reStructured Text (RST) to HTML. Also, Pandoc does not support converting AsciiDoc to HTML. For Pelican, the support of Markdown, RST, AsciiDoc and Org-mode is good by using Python modules or plugins.

I am using AsciiDoc on both Pelican and Astro, so it does not reflect the situation that most people use Markdown. But let’s what happen here.

Pelican wins this time. On my setup, it spends a total of about 20 seconds. It spends 10 seconds on actual converting AsciiDoc to HTML. It is using the AsciiDoctor Ruby binary for conversion (faster). So, it took about 10 seconds on loading plugins, getting update from CDN, copying final output files to distribution directory and running the html validator on the output files.

How about Astro? It spends a total of about 25 seconds. It spends about 10 seconds on actual converting AsciiDoc to HTML. It is using the AsciiDoc.JS (JavaScript implementation, transpile from Ruby), which is slower. I may investigate calling the AsciiDoc Ruby binary directly, but it requires changes and AsciiDoc extensions and AsciiDoc.JS extensions are different (AsciiDoc Diagram vs Kiroki). Hence there would be more changes in the conversion module. Here, Astro spends about 5.4 seconds on collecting page data, 3 seconds on vite, 3.8 seconds for building for SSR. Please note Astro has performed tree shaking whereas Pelican has no tree shaking.

Since Astro has performed tree shaking, Astro produced a smaller output file size. Here’s some stats for loading a same article (same Markup language) in a local network: