Crafting a Website for OpenTech(AUC)

Building this website was a nice way to let non-coders in our group get acquainted with terminology from the FLOSS world. Non-experts can quickly learn the basics of Markdown, thus getting the chance of using git from the very first week of work. Here is what we used! Feel free to browse the project’s repository if you are curious about the technical details. In this blog post, we limit ourselves to a non-technical overview for amateurs. Experts will appreciate how we try to extensively use declarative languages. This is done by delegating as much as possible to markup and configuration formats.

Forge: Codeberg

We wanted to share the code with people all over the world so that they could rerun, study, change, and redistribute it. So, we publicly uploaded it to Codeberg. Unlike more widely known forges, such as Microsoft GitHub or GitLab, Codeberg is:

• itself FLOSS software;
• maintained by a non-profit organization;
• hosted in Europe;
• actively working on federating with other forges.

All OpenTech(AUC) projects are hosted here. Everybody is free to inspect our work and file an “issue” is they think something is wrong or missing. They can even copy (“fork”) our work to make whatever modifications they like to their own version. Then, if they’d be happy to see their work in the original version of the project (“upstream”), too, the can open a “pull request” to propose their edits are actually used to improve our project.

Static site generator: Hugo

To automatically generate a website from our writing, we use a program called Hugo. The websites generated by Hugo are called “static”: running Hugo once is enough to get the definitive, never-changing version of your webpages. This way, when somebody visits our website, these very same webpages are always ready to be sent to the visitor’s web browser as they are. There is no need to build them on-the-fly (that’s what a “dynamic” application would do)!

Theme: Open Binario

Everybody can build their own Hugo theme to customise the aesthetics of their website. The one we started from is called Binario. As Binario is FLOSS, we were free to slightly tweak it. We called our custom version Open Binario, and hosted its source code on Codeberg.

Markup language: Markdown

What’s the format we need to use when writing content that is to be processed into our website by Hugo? It is called Markdown, and it is very easy to learn. Hashtags prefixes indicate headlines, single asterisks indicate italic text, and so on…

If we want to specify metadata (title, author, date, description, tags..), Hugo lets us add it at the beginning of the file, before the content itself.

Configuration language: TOML

Settings for our website are also nothing but plain text. Our hugo.toml specifies the title or language of our website. In addition, data/authors.toml stores information about the authors of our blog posts, and data/social.toml about our communication platforms.

CI/CD engine: Woodpecker CI

Despite its name, we actually use Woodpecker CI for two distinct tasks: Continuous Integration (CI) and Continuous Deployment (CD). In both cases, we are giving Woodpecker instructions via the .woodpecker file.

Continuous Integration

We would like to see new pieces of code coming form our contributors continuously (that is, frequently) integrated in our project. To be confident the code actually works, we have Woodpecker run some automated checks on the code of newly opened pull requests. In our case, Woodpecker is run on Codeberg’s servers.

To be fair, the only automated check we perform is running Hugo on the proposed modifications. If Hugo does not complain and actually outputs some website, that’s good enough for us.

Continuous Deployment

Not only Codeberg is hosting our code, it is also giving a home to the resulting website generated by Hugo. The latter service is called Codeberg Pages. To make sure or codebase is continuously deployed (that is, the generated website on Codeberg Pages is always built starting from the latest version of our code), we ask Woodpecker to automatically build an updated version of our website every time, and then push it to Codeberg Pages.

Conclusions

There’s no need to program or know programming languages to make a website. But, much like programmers, we also chose to manipulate text files following very specific syntaxes, ready to be processed by a machine. This allowed us to get a programmer-like experience, where we got used to common workflows in software development.

Hopefully we managed to convince ourselves that computing, when done right, is no black magic at all.