Migrated to Elderjs from pelican

two elderly playing chess

Been hearing a lot about svelte and I did watch Rich Rethinking Reactivity about 2 years ago. I was still working and svelte is stil young. Now that a lots of bugs have been fixed and sveltekit is in beta, i have to scratch my itch to learn it.

So about a month ago i decided to have a serious look at svelte. I spend about a week with svelte, going through the tutorial and docs. Watch and follow some tutorial on youtube. It was wonderful experience. I like it more than react and i'm not a react guy. So i spend another week playing with svelte and sveltekit. However playing with sveltekit which is in beta is not as fun as i though. Decided to look for alternative before i go deep to understand how sveltekit work and i stumble upon elderjs. (I know lots of people has created awesome thing with sveltekit but i guess it just not my time, will look into sveltekit again later when i got time to).

It's been almost two years since my first post on this blog. Back then my goal was to create a static site for github page, but i'm more comfortable with python than ruby. Lots of choices back then, but i decided to go with pelican because my work that time mainly using python. There's nothing wrong with pelican, it just i grow out of it and i did broke the dev server somehow with my config.

Main reason i'm investing my time with elderjs is because i wanted to use svelte, as fullstack dev, using elderjs it allow me to focus with one programming language for tools and source which i already use when developing the blog theme using gulp. and lastly i want to scrath the itch to learn something new.

A bit of my background, I do use python extensively mainly for data processing, developing internal tools at my previous work and simple scripting that doesn't require a GUI.

Also a diclaimer, this comparison might be bias.

Configuration and boilerplate

In this post I just want to make a comparison between pelican and elderjs based on my experience since i've used both. Pelican is still active on their github repo and that is a good thing. First things first, let's take a look at my flow when using pelican. Pelican is quite heavy with the config file, where we need to have separate file for dev and publishing. Both pelicanconf and publishconf file are quite similar. We can generate our project using pelican-quickstart --path project_directory and it will generate your starter project after answering a series of question.

Looking at elderjs, elderjs is opinionated static site generator. To start an elderjs project we simple create a new folder and use degit to copy the minimal template repo. Elderj js exposed 3 config file which are elder.config.js, rollup.config.js and svelte.config.js. However only two will be used most of the time. We will use svelte config to set svelte preprocesses and elder config for the rest of the time.

File Structure

Pelican separate our theme source file from the blog contents which is a good things. We can define our own structure as long as it is inside our content folder, this structure need to be defined in the config file. However the themes are quite strict and we will discuss about it in the next section.

pelican_project/ 
├── .venv
├── themes/
│   └── my_themes
├── content # this your source folder
├── Makefile
├── pelicanconf.py
├── publishconf.py
└── task.py

The following are the important files and folder for a functional elderjs project. assets is where we put our static files. Routes is where we define the page template and routing config if needed. Components hold smaller svelte components. Layouts are unlikely to be touch unless you have different layouts for each page. We look into elder more in my upcoming post.

.
└── elderjs_app/
    ├── assets
    ├── src/
    │   ├── components/
    │   ├── layouts/
    │   ├── routes/
    │   ├── build.js
    │   ├── cleanPublic.js
    │   ├── hooks.js
    │   ├── server.js
    │   └── shortcodes.js
    ├── elder.config.js
    ├── rollup.config.js
    └── svelte.config.js

Templating

Pelican still using the theme system where we develop our own theme or download existing theme from pelican theme collection. Creating a theme is quite strict where we have to have specific file and left it empty if we don't use it. The template is pretty much like a blogging system where we have the tags page, author page, categories page, archives page, though we can disable them. Though we can have custom template for specific markdown contents by declaring Template: template_name in the meta section. This means for a custom page we need to write an empty markdown file with only meta and the actual html which counted as template inside the theme folder.

With elderjs however there are no defined way how we want to develop our theme or components. We are free to define that on our own. The only rules is, pages needs to be in the route folder along with a route.js file and source file should be in the src folder so that dev server can track the changes. With the latest version of markdown plugin, it now support to fetch markdown files from outside of the src folder.

Development Server

I broke the pelican dev server with my theme and i have no idea why because the error CRITICAL: TypeError: cannot pickle 'generator' object is just too verbose. So i just live with it for while and just open the html output in the browser since the build works just fine.

Elderjs dev server can be run with npm run start or npm run dev and it will open dev server at http://localhost:3000. It works just fine and i haven't seem to break it yet. However at it current state elderjs dev server doesn't support HMR or incremental build yet, but AFAIK Nick is working on it to make it work.

Plugins Ecosystem

The plugin ecosystem is quite big where it have about 147 plugins that we have to download into pelican-plugins inside our project file and then declare it inside the config file. I don't have much interest to develop pelican plugin, but i did hack three of them to make them work for me.

Elderjs support plugin as first class citizen which means we can easily createa an extension with it. Elderjs extension utilize elderjs hooks which is a nice thing because elderjs took care all the stuff that svelte do and provide an interface during the process. However there are not much plugins available yet, though i have release 2 plugins and 1 is listed on the official plugin list. There are 8 official plugins at the moment.

Data Source

Pelican only accept files in reStructuredText or Markdown whereas rst is quite popular among python user or i don't know, i only use python for extensively for work and some simple scripting on my own.

Elderjs official support markdown and api. There are example to do both. Plus we can easily at our own source if needed. If you are interested how to use data source from an API, i recommend to watch Nick presentation where he introduce elderjs at svelte summit 2020. Elder.js Intro for Svelte Summit 2020.

Pagination

Pelican support pagination natively via the config file, where we can define per page pagination, disable pagination completely, pagination page template and advanced pagination to define custom slug for the pagination index.

Elderjs doesn't have built-in pagination, which mean we have to implenent our own. But fret not, i got you covered. I just release an elderjs pagination plugin to handle the pagination for your markdown blog with proper example and api.

Code Highlighting

Pelican do offer a syntax highlighting via the python markdown plugin, codihilite which utilize pygments. Pyments support extensive list of programming language and still being actively maintained. I seriously have no idea how it works or how to make it works, so i use highlightjs previously. But if you are interested you can check out the docs.

Elderjs on the other hand support shiki via the official elderjs markdown plugin, which IMO the best syntax or code highlighting for static sites. It support the built-in and custom shiki (shiki 0.2.6) theme which means we can exactly use the same theme we used on VSCode. However if we are using our own parser or API to fech our blog post or contents, we have to implement our syntax highlighting interface.

Using Static Page

Pelican offer a way to bypass the theme and use a static html file like 404 page. This can be done by creating a markdown file in the contents folder and add

On the contrary, there is no reason to use static file in elderjs since we can always configure the route and customize the page as we want bypassing any theme or even use different layout. However as it current state in elderjs, 404 page will be generate as site/404/index.html and there is no way yet to override it.

Building the output

Pelican uses another config called publishconf.py which i find it to be repetitive. So i just use the same pelicanconf.py that i use for development which i broke for development. By changing a few commening out few param and it's done. I have no idea why they decide to use two config file instead of just one and accepting command production or dev flag or something.

With elderjs, simply run npm run build to build the output and we are done. No separate config file or makefile to care about. npm run start to run the dev server.

Partial Hydration

Pelican have no partial hydration built-in, but we can always use javascript wherever we need via the theme. Thise means we have to write external javascript to handle interactivity.

With elderjs and svelte are both javascript, we simply have to marked hydrate-client={{}} on any part of oue UI that need to be interactive.

Custom URL

Pelican have support with for custom url which we need to be define in the markdown meta section and again we need to add the custom template inside our theme folder. Afterward

Elderjs url can be customized or change via the hooks. While for the markdown plugin, we have to supply our own slugFormatter. Elderjs support pretty url by default and does not support file based url as of current version (v1.4.13). But it might support that in the future.

However for custom page for example page 404.html with either SSG, we still have to configure our server side to redirect to our 404.html file.

Publishing

Publishing are straight forward, we can either use the github pages style publishing where we use publish the output folder on separate branch, and then use this branch for publishing. This method will also reduce build quota for CICD.

Both can be published to github pages, gitlab pages, netlify, vercel, aws or anywhere that support static site hosting.

Documentation and resources

The docs that i love the most in the python package is the request package. Both have complete documentation, however they both lack walktrough or step by step tutorial for beginner. For advanced user, the docs are pretty much helpful and they can easily look at the source code if necessary since both are open source project. However need to note that pelican is release under AGPL license while elderjs is released under MIT.