Migrating my Jekyll website to Codeberg Pages

I've been really busy these days and haven't made any posts. Despite having plenty of drafts for the blog, I couldn't find time to sit down and write.

Fortunately, unlike any algorithm-based platform, this blog allows me to write at my own pace and as I wish. After all, there's no financial support or, with all respect, any kind of obligations to readers. The dynamics of this blog is quite simple: I write what I want and like, while people who are interested in what I have to say, read it, and when they want, they interact with me by email or on fediverse. And this has been working very well.

Okay, back to the point that I've been 26 days without posting. I believe that one of the reasons that makes me post less - besides the time factor - it's my publishing workflow. This blog is powered by Jekyll, where I write everything in a .md file, then I push the modifications to my git repository. If I want to add some picture, this process becomes even annoying, as I convert the image to lightweight and web-friendly format, strip the metadata, and upload it to my s3 storage.

Over the last week, I tried to improve this process by migrating to an opensource blog publishing platform called Writefreely. It is

a distraction-free writing environment, it federates via ActivityPub, so any ActivityPub-enabled service can follow your blog, bookmark your posts, and share them with their followers.

At first glance, it looked amazing. In fact I could focus on my writing, but it came with some cons:

  • I couldn't migrate my posts to another git platform easily (as I did - and will explain further in this post - moving to Coderberg);
  • Customizations are way more complex;
  • There would be a monthly cost (not only financial) to maintain a vps for hobby project.

Accepting that I'd continue with the same workflow for the present moment, I dedicated myself to my next task: migrate this static blog from github to codeberg.

Why to migrate? You might be questioning yourself.

There has been a whole heap of discussions about Github this month, mainly because of Copilot. For those who don't know, Copitot is a proprietary service built on top of the hard work of the open source community with Artifical Intelligence (AI). It raises a number of important questions on which I will not be writing about in this post, but it certainly raises some flags for me.

I try when possible to use software and services from companies that I trust or that are closest to my values. That's why I decided to migrate. Github, obviously, is a great tool, and I will keep using it in situations where I cannot opt-out, for instance, due to the lack of federation with git.

Okay, after this introduction, let's talk about the migration itself.

Moving the repository was pretty straight forward. I created a new repo on Coderberg and pushed my local files.

If you want to migrate metadata like issues, releases and a wiki, you can use the Codeberg's migration tool. This process is well documented on Codeberg's Docs.

Here things get interesting...

I use Jekyll to generate this website's static files, and publishing it was easy, as Vercel simplified the CI building process. Altough, there's no integration between Vercel and Codeberg as I'm writing this post.

At this point I thought about giving up and moving my repository back to Github, but fortunately Codeberg Pages allows us to easily publish static files generated by Jekyll via Git on Codeberg.org. The process is not automatized, yet is not complicated. You just have to get used to it.

The first thing I did was to create a new branch called pages.

I decided to separate the main and the pages branches in different local directories, so I would not mess things up:

git clone https://myrepo.codeberg.org websites-pages

git switch --orphan pages git rm --cached -r .

Then I generate the static files to be added to the pages branch:

cd /path/to/your/repository/where/MAIN/branch/is

bundle exec jekyll build --destination /path/to/your/repository/where/PAGES/branch/is

then I pushed the new files to the new branch:

git add .

git commit -m "Initial commit"

git push origin pages

From this point, the website was working and accessible at https://username.codeberg.page/reponame/ and https://username.codeberg.page/reponame/@pages.

However, due to some hardcoded links in my static files, this messed up with basically all content, as well as the style.css file.

To fix this, I needed to configure my custom domain.

To use a custom domain, I created .domains file in my repository and wrote my domain.tld domain name in it.

In my case, because it is a zone root and Alias is not supported, I added the following DNS records:


AAAA 2001:67c:1401:20f0::1

TXT repo.user.codeberg.page

If CNAME is supported, you can just add this DNS record, instead of the entries above:

CNAME repo.user.codeberg.page

In a short matter of time the blog was up again. Codeberg Pages took care of generating the certificate with Let's Encrypt, and everything was working as before.


  • The official Codeberg Pages documentation you can find here.
  • I miss being able to configure some security headers with the vercel.json file, as well as being able to redirect some links. But this is not a big problem for me at all.
  • Be sure to include the following line in your _config.yml, otherwise Jekyll will delete the .domains file in future builds.
  - .domains
  • Remember that there is no CI process involved, so you need to push the static files to the branch pages whenever you create new content.
  • Although a little more work, site publishing is faster, as the static files are being generated locally and pushed via git, so they are instantly available.
Show Comments