Some time ago, I shared my experience using Docusaurus to document an OCaml project, highlighting the integration between Docusaurus, ocaml-mdx, and the dune workflow (previous post here).
Today I wanted to share that Iāve resumed this exploration in documentation tools to try and integrate odoc-generated pages into Docusaurus, with the aim of creating a somewhat minimal template/example for this.
Integrating odoc posed challenges - Iāve written about the (pragmatic) approach I took here. Iām linking this odoc issue too, for reference about exploring more native solutions for this interop.
Have you too tried this āmagic comboā of Docusaurus, Odoc, and OCaml tools? And if so, how did you approach it? Do you have insights or suggestions? If this sparks your curiosity, please donāt hesitate to engage with the repository.
Iāve never used Docusaurus, but I have some experience creating a documentation website with odoc and jekyll (see Patricia Tree | Codex). It used odoc nice json output (dune build @doc-json) to generate the docs in an easy to reuse manner, and then a custom jekyll plugin and layout to render them.
Overall its a bit hacky and I encountered a few unique issues doing it (like odoc output being broken since it relied on whitespace for indent in html and jekyll just-the-docs automatically stripping extra whitespace). But Iām pretty happy with how the result turned out.
I hadnāt seen a setup using @doc-json before. That looks pretty interesting and aligns well with what I am trying to achieve. Thank you for sharing!
I like it! From a few prompts in the search boxes, it looks like Search Codex searches the entire website (including odoc APIs), whereas Search patricia-tree API is the equivalent of the sherlodoc-powered search box. Is that right? Is the Search Codex provided by Jekyll?
I havenāt made much progress with my experiment yet, except for perhaps one small step. I tried enabling an Algolia Search Box on a Docusaurus site that includes the odoc files in the static directory (here). Unfortunately, the odoc pages are not presented as search results by the Algolia Search Box by default. However, I can see indexed objects related to the odoc files in my Algolia Dashboard for the project, so Iām guessing the crawler does work, and itās a Docusaurus config that needs to be adjusted. To be continued.
Thanks again for showing a live example involving @doc-json. Perhaps that could be part of a better answer for the Docusaurus integration as well.
Yes exactly, the āSearch Codexā bar is auto-generated by Jekyll (Its a part of the just-the-docs plugin). It is based on a Jekyll generated JSON list of all pages and contents (which I had to hack a bit to add the odoc pages as well see here).
The āSearch patricia-treeā is the sherlodoc powered one, I just copied the HTML/JS elements from the classic odoc page and edited the paths where relevant to fit the new site layout.
Its a bit clumsy having two search bars but I couldnāt be bothered to dive into the JS and merge them properly.
+ 