Deploying a Quarto website to Codeberg

Quarto
Codeberg
Published

2023-12-28

I currently host my website on Codeberg. Much like GitLab and GitHub, Codeberg provides a git-based development environment. All three also allow users to host static websites through Pages [1],[2],[3]. What differentiates Codeberg from the others, however, is that it is run by a non-profit, community-driven, privacy-focused organisation.

[1] GitLab Pages
[2] GitHub Pages
[3] Codeberg Pages

For creating the website that I deploy on Codeberg I use Quarto, which is a relatively new open-source publishing system with a technical and scientific slant. Quarto supports several languages (R, Python, Julia, and Observable JS)[4] and numerous output formats (e.g., static websites, PDFs, Microsoft Word documents, Jupyter notebooks). While it’s versatile, this isn’t at the expense of ease of use — it’s also intuitive not to mention well documented.

[4] You’ll notice that these are languages that are often used in Data Science. This is because Quarto is developed by Posit — formerly RStudio — which specialises in tooling for this field.

I like Codeberg’s mission and the convenience of keeping source code together with the rendered website, but I ran into a small technical obstacle that needed to be overcome to develop a workflow for using Codeberg in concert with Quarto.

The problem

When Quarto renders a website, it does so into a designated directory. (I believe Jekyll adopts the same approach.) With this in mind, since 2016 GitHub have allowed Pages websites to be published from a directory from within a repo[5] rather than just from the root of the repo. Codeberg doesn’t yet provide this functionality; however, there is an alternative means to the same end.

[5] GitHub’s announcement.

A solution

circlebuilder, a Codeberg user, shared a script that has proven super helpful in solving this problem. I have tweaked it a smidge to fit for my own situation. The crux of the solution is that while Codeberg doesn’t allow a website to be deployed from a different directory, it does allow a website to be deployed from a different branch. Specifically, Codeberg Pages defaults to deploying from the pages branch. This means the source code can be kept on the main branch, whilst the rendered website can be kept on the pages branch.

The script below is meant to be run in the root directory of the local repo after the source files have been updated

#!/usr/bin/env bash

quarto render

git clone git@codeberg.org:DanielReed/pages.git pages.git
rm -r pages.git/*
rsync -av _site/* pages.git/

cd pages.git &&
git checkout --orphan current &&
git add -A &&
git commit -m "Deployment at $(date)" &&
git branch -m pages &&
git push -f origin pages &&
cd .. &&
rm -rf pages.git

In short, the script works as follows:

  • Renders my Quarto website, outputting files to the _site directory
  • Clones my Pages repo & nukes its contents
  • Copies the rendered files into the empty repo
  • Adds & commits the rendered files
  • Pushes the commit up to the pages remote branch
  • Removes the cloned & updated directory

To make the script executable, use chmod +x script-name.

Back to top