Progress Notes: raga - Static Site Generator

This document serves as a progress log of my work on raga - a static site generator in OCaml. This is also the project I want to submit as my capstone project for the Computer Science course I am enrolled in. This document is organised as a short description of the project, followed by a reverse-chronological list of progress notes.

About raga

This is the proposal I had drafted in June 2025: project proposal. The project was initially called pushpush, but I've since decided to rename it to raga.

The idea is to make a static site generator in OCaml that is capable enough to generate & deploy my own website + some other ideas that I have. I also want to use this as an excuse to write non-trivial software with OCaml--and in the process find out what is easy / hard to do for me in OCaml.

The project was planned to have 2 parts for me to build:

  1. [done] A Handlebars templating engine
  2. [done] The actual static site generator that would make use of the templating engine

Since then, a third got added and completed, which is a parser for the huml configuration language.

Links

  1. raga:
  2. handlebars-ml:
  3. huml-ml:
  4. Project Proposal: Google Docs

23 November 2025

raga

Usability testing

Adding chess games to website

I implemented a PGN template for my own website to test the capabilities of raga. I had to allow front-matter in non-markdown files to make this work, but it works quite well. For example, this is the chess games list on my website: /chess.

I'm not particularly pleased with this approach because I need to replicate metadata information that is already there in the PGN into the front-matter. This is not strictly needed because it can be done from JavaScript, but this helps SEO bots and RSS feeds.

Building template with Unicode website

I did some more testing with trying to implement a website template with Unicode in the configuration. That case also works well. I ran into some problems with setting up the default case. I've added GitHub issues to track my work on this task.

The setup task is also slightly long in the sense that I need to setup the directory structure. I also discovered a bug here that expects the partials directory to always be present. I want to change that to throw a warning in that case.

Feature - Build summary

I added a feature to the CLI to display useful build stats at the end of every build. This gives some visibility into what was generated:

build-summary

It also shows how long it took to build something. I like the current build times too.

publishing to opam

raga has now been published to opam. I will start talking about it and provide a single binary for installation after this round of fixes and some testing.

handlebars-ml

I'm quite happy with how stable this has been. I want to refactor the helper functionality to:

  1. have more power, so that for example one helper can be used to add the boilerplate HTML for enclosed markdown content.
  2. give better errors and warnings when the arguments passed are incorrect (for example, when they have wrong types).

huml-ml

I recently worked on the BNF for this and we have a new spec with a few changes that I want to update the OCaml and other parsers for.

TODOs:

03 November 2025

raga

I got started and have a working raga implementation. This website now runs on raga instead of hugo. I used the same content files for the most part, with some minor changes, and I was able to build a somewhat large website with it. This gives me confidence in its power. While working on it, I found some bugs/improvements in the handlebars implementation that I then fixed.

I think I've come up with an interesting config solution that works kind of like a pipeline-definition language. I define the source files, the processing to be done on them, and the place to output them. I'm working mostly with markdown and have frontmatter support for exclusion rules. I also want it to be a general-ish pipeline tool that can let me build arbitrary files. For example, I want to take my PGN files that contain chess analysis, and publish them as HTML pages with the correct transformations. Adding new functionality is done with OCaml code at the moment. I might want to change that to be able to generalise to bash scripts at some point. I'm also getting the feeling that perhaps s-expressions might have been a nicer, powerful format for the config and that I'm trying to emulate them into huml for the config syntax.

I have been able to add all the features from the previous wishlist, and more. I'm happy about that.

State so far:

TODOs:

18 October 2025

handlebars-ml

I have been able to get to a version of handlebars-ml that I feel comfortable using. I have also published it to the opam package manager. I have added enough tests for me to feel comfortable with the featureset that is in there. There is support for helpers, partials, and all the basics. Inline partials are not yet supported but I am okay with that because the same usecase is possible with workarounds.

Some areas where I feel like improvements are possible are:

huml-ml

Fresh off writing a new parser for handlebars, I got tempted into writing another one for a new & strict configuration language called huml. I find it interesting and useful. I think I want to add support for parsing frontmatter and configuration in huml. Maybe even start with it as the default.

I wrote about it to Kailash, a maintainer of this project, who was happy to see it. Since then, I have moved the implementation upstream to the official huml org. I am also working on a BNF grammar for it in addition to some bug fixes in other implementations. I have been enjoying this. I enjoy writing parsers and this kind of working with the community makes me feel useful.

(I have oddly enough written >3 parsers, which I think is more than the number of parsers that most engineers are likely to write).

raga

Per the schedule, I think I'm running ahead on the handlebars-ml work and just-on-time on raga. I have a design architecture in mind. I think the goal I have in mind--to be able to compile my own website--keeps me grounded in terms of what I need to build.

For the first version, I have in mind that it should work somewhat similarly to hugo, which is the generator that I currently use.

Specifically, it should be this featureset:

I plan to work on this in the next couple of weeks.