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. [wip] 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.

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

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:

  • better support for date & time parsing / rendering. I don’t want to bloat the templating engine, so I’m thinking this can instead be part of raga.
  • the CLI is not enough on its own to support adding new helpers. As of now, the workflow for that use case is to use the library, write OCaml code for the helpers and compile that. I think I’m okay living with this for the moment. I have been considering small scripting languages for this use case though.

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:

  • Parse frontmatter in huml and pass that to the theme/template
  • Parse config in huml and pass that to the theme/template
  • Allow generic templates in a theme (e.g. _blog.html that will work as one template for all blogs).
  • Translate markdown content to html
  • Make a template for the RSS feed

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