Using Docusaurus to document an OCaml project


I wanted to share some positive feedback on using Docusaurus to document an OCaml Project: Bopkit.

Among the reasons I chose to experiment with it was its compatibility with ocaml-mdx and the dune-runtest & dune-promote workflow. That is, a lot of the dynamic contents that shows in the doc stays in sync when the code is updated during development, including file parts, expect tests traces and mermaid diagrams.

I also liked the fact that the contents is mostly based on *.md files that are present in the tree, and those that can be browsed directly from GitHub as well (such as all the found at the leaves of the project’s directory structure, which are rendered similarly by GitHub).

This integrates well with GitHub and GitHub Actions in that the doc can be hosted directly in the GitHub pages of the project.

I’ve also experimented with their support for a global search box via algolia which was overall straight forward to setup.

As a side note, I just went through their v3 migration guide, and I liked the experience.

Putting it out there in case you’re interested in trying it out, or simply want to browse an example of a Docusaurus setup involving an OCaml project using ocaml-mdx and dune.