Quest to Cloud Native Computing

Migrating my blog from Pelican to Astro


Modified: Sun, 2022-Mar-27


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:

  • At document build time, the list of articles and pages are created. Developers can access the metadata by using Jinja2 variables like {% articles %} or {% pages %}. Then the developers could generate a list of articles (like the archive page) much easier.

  • At document build time, the list of categories and tags are created. Metadata is just {% categories %} and {% tags %}. Developers can access the metadata to generate a list of articles grouped by category or tags. Also, it does not require the developer to write additional code to generate a list of categories and tags.

  • Pelican provided several locations that could invoke the plugin when generating the document. It could invoke the plugin before reading the article from markup, before writing the article to HTML, after writing the article to HTML and etc. This gives a lot of flexibility.

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

  • Licensing. Pelican and many Pelican plugins are released with the AGPL-3, GNU Affero General Public License. It is a strong copyleft license and sometimes it is not desirable for some projects or developers. There was a discussion about it. The conclusion is that if Pelican wants to change the license away from AGPL-3, it requires all the consent of about 350+ developers. So, the AGPL-3 license could not be changed. The prime developer said it should not need to worry about the license of the output files generated by Pelican.

  • No tree shaking for the CSS framework.


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:

  • Astro supports lots of JavaScript frameworks. Astro run on Node.js so there are lots of JavaScript libraries to use. Besides that, tree shaking is supported.

  • Astro supports partial hydration. With partial hydration and a supported JavaScript framework, developers could reduce the amount of code send to client, they could specify when to load components (when the components is visible, when the page is load or when the browser is idle).

  • Astro is released with the permissive MIT license.

  • Here’s some of the Astro integrations.

About the migration and observations

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

  • Metadata

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).

  • Meet rehype

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.

  • Dark mode

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

<h2 class="text-zine-800 dark:text-white">Heading</h2>

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.

  • Support of other Markup languages

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.

  • Built time

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.

  • Output file size

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:

  • Pelican: 31 requests, 845KB uncompressed data transferred, page loaded in 1.1s, DOM content loaded in 241ms

  • Astro: 31 requests, 763KB uncompressed data transferred, page loaded in 0.52s, DOM content loaded in in 210ms

Table 1. Summarizing the characteristics, pros and cons of Astro and Pelican
Items / SSG application Astro Pelican




Programming language(s)

JavaScript, TypeScript, many frameworks (Svelte, Vue, React, SolidJS, Alpine) and Lit

Jinja2, Python(for writing plugins)

Easy of use


Very easy

Markup language support

Default is Markdown. Have module for Pandoc. Need customization for AsciiDoc

Good support for Markdown and reStructured Text. It also have plugin for AsciiDoc

Tree shaking or bundler

Vite.JS, PostCSS

No bunder by default for JS. For CSS, can integrate with PostCSS

Built-in news feed format


RSS and/or Atom


  • Concrete concept of articles, pages, category, tags. It is easier to access these built-in elements for web development

  • Product is mature and stable


  • By default, it does not have a pre-defined concept or built-in elements for 'category' or 'tags'. You have to build or develop your own design. (This could be good or bad, it depends)

  • Product is under heavy development so the features and configuration keep changing

  • No tree shaking for CSS. No partial hydration for the JavaScript components.

Share this article

Related articles


No. of comments: 0

This site uses Akismet and Google Perspective API to reduce spam and abuses.
Please read and agree the privacy policy before using the comment system.