There’s is more to documentation than .mli files and and yes your are missing out. But it’s not about the renderings: it’s about the links.
That being said with a good editor you can browse them directly in it if you don’t want to switch (for myself there’s little I do that does not involve a browser, if only documentation production, so editor and browser side-by-side is the setup YMMV).
This is not true. GitHub renderer renders some HTML (for example summary-details elements but I’m sure more). It does ignore style attributes.
Edited to add: Dave is obviously right, I overlooked the fact it’s about the inside of code blocks.
Update on the current thing we’re attempting.
We’re going to probably write a tutorial using ocaml-mdx. The big advantage is that we are guaranteed that the library and the tutorial cannot get out of sync, because it’s checked in CI. Then we’re going to extract and copy the md files to the website.
@davesnx to confim, what’ you’ve implemented is odoc extracting to markdown, not odoc being able to ingest markdown pages right?
If so, I’m thinking about maybe writing the tutorial in mld + ocaml-mdx and then extract to markdown and copying it to the website. So that a single source will give me both offline documentation and website-integrated documentation. The downside is the lack of links online, as @dbuenzli mentioned.
For code highlight, that’s totally true. If you inject links and other html inside code, you don’t get the expected html output and also, break the syntax highlight.
Here we aren’t degrading the user experience, in fact, gh renderer or static-site generators have syntax highlight in place that do not support random html elements inside.
As explained here: 2025 Documentation best practices - #24 by davesnx
What we are lowering is the features from odoc markdown compared to odoc html, which again, adding a flag to markdown which enable rich-html elements would be the best of both worlds.
Of course you are but if you prefer to call that a “lowering of features”, so be it :–)
Note that depending on the CMS you use for the website, the aforementioned JSON output could be more appropriate to wrap your page template around (at least for the few CMSs I have been working with in the past I don’t think it would pose any problem except for a few php lines to write).
Btw. if you didn’t decide on that CMS yet, maybe these lines can turn into a couple of OCaml ones (or the language you wish in fact) by using soupault and writing a small soupault page preprocessor to convert these JSON files into HTML ones wrapped by your site’s page frame.
Read here for a comparison with other static site generators.
Realise I didn’t answer this.
A bunch of small things, but the lack of things like unfoldable blocks, admonitions, etc.
Take a simple example of a nice documentation Running On Device · React Native, small things like admonition are missing from odoc and make reproducing this difficult.
Sure all these things can be added to mld, but it’s annoying to keep re-inventing the wheel when they exist in markdown and are supported by so many markdown readers and html compilers out there…
In different and incompatible ways… since nothing like that exists in CommonMark. Mind you there’s not even an established syntax to properly reference a section header (and if your processor has one and you misname the anchor, you get garbled plain text, and if you switch the processor you might end up with dozens of dangling references).
The problem with all these markdown readers, HTML compiler and CMSs out there is that they are utterly bad at managing the single thing they should do well: your local hypertext data structure. This is something odoc excels at and is essential for documentation maintenance.
That being said raw html is a thing in .mld files so if you really need a bit of attention you can certainly hack your way by inserting an the odd bit of raw HTML for an admonition. Here’s an example:
{0 Admonish}
{%html:<div class="warning"> %}
Be careful {!section} is incomplete.
{%html:</div> %}
{1:section The incomplete section}
An incomplete section
P.S. My biggest gripe at the moment about .mld files is that no-one has done an emacs mode for them so far.
Btw. I thought you would rather end up suggesting that learning the ocamldoc language is a pain versus using CommonMark.
Since the title of the topic is broad I thought I’d mention here that at some point I defined and implemented (and used at small scale) ocamlmark.
Using a bit the translation left me rather unconvinced, especially the lack of a notion of erroring in CommonMark and the space sensitivity is a pain for documentation production and maintenance. You can read about the tradeoffs here.
I mean, it is uncomfortable to learn a new language, but I’m willing to do it if it’s worth it. I agree md is not the best though. But odoc still feels quite a few versions away from being as good as required to produce truly beautiful doc 
(Not for lack of trying, but the community is small, and there are few maintainers/authors on odoc. They’re already doing an amazing job, these things take time, I know that!)
I’m not sure what is missing here for that. Personally I think this is false. If you know any better open issues.
Beautiful is a matter of look and nothing prevents you from devising a look for odoc produced documentation to parrot whatever is à la mode these days.
However I’d just like to caution on focusing too much on the beautiful. I have seen beautiful documentation websites that were just a pain to work with in a daily routine, or worse that became “more beautiful” but less usable (e.g. MDN) or only usable on a 32’’ screen.
Focus on the information structure (the links) and access patterns of your users and optimize for them. For example count the number of clicks from the landing page to access a piece of information you deem essential. Think about the fact that users are going to peruse a given page over and over and thus optimize for repeated accesss, not for a first read. Etc.
Your “beautiful” comment actually reminded me that you complained there was no admonition syntax in ocamldoc. In fact for years I have been doing this as follows:
{b Note.} You should pay attention to that.
{b Warning.} This function must be applied with care or it
will segfault.
Which not only works very well but is also less intrusive than these kind of eye catching boxes in the documentation you linked to, it flows with the text. Does the admonition need to catch my eye each time I read the page ? Often not.
Assume we render these “beautiful” admonition boxes in function doc strings. Their look would clearly interfere with the page scanning process by drawing attention to them. But when you are scanning the page you are not interested in these admonition boxes: they pertain to the functions themselves. “Beautiful” is not necessarily usable and the trick given above works better in this case (that’s not to say we couldn’t have an admonition syntax in ocamldoc and style it unobstrusivly in the doc string of structure items, it’s just that it’s not a good excuse for not using odoc :–)
P.S. It seems to me that programmers love to talk about documentation systems and complain that they are not there for their task and how much doc they would write if they had a good system. Let’s be frank here, the systems have always worked (even the venerable ocamldoc) and you could hack you way around (before we had .mld pages I’d just have them at the end of modules). I think it’s just an excuse to procrastinate or not to write docs ;–)
Not fully false of course 
I have started writing my documentation in odoc + mdx in the end, for the benefits of having code that I can guarantee is in sync with my tutorial in the end. So I’ll probably end up opening issues.
I don’t think there’s anything major missing, it’s just a bunch of small papercuts that make it discouraging over time. For instance, right now, I’m struggling with mld + mdx – though admittedly it’s not really an odoc problem.
If you’ve ever tried to write documentation in e.g. docusaurus, everything you may want to do is possible and with relatively little effort (except interacting with the OCaml ecosystem, and provided you are somewhat familiar with javascript in the first place). The thing is, there’s an entire team of people at Facebook who’ve been paid for years to create and maintain the thing. If anything, the fact that odoc is so good given the comparative amount of maintainers is incredible!
I guess what I’m saying is more: maybe we (as a community) should focus with enabling interop with existing tool rather than try to re-implement every good idea into our ecosystem.
The thing is that we are talking a bit different things. You seem to be in a case where you also need to cater for non-OCaml users on a dedicated website. odoc can certainly be twisted into that but that’s not odoc’s primary goal which is zero-effort doc generation and deployment for OCaml libraries and tooling (not only API docs, that includes tutorials, cookbooks, reference manuals, sample code etc.)
Interoperability or use of docusaurus will not enable better documentation user experience as far as OCaml programming is concerned. In fact if people start using it, it will make it worse (the reason why has already been mentioned but for a concrete example the day I want to use say @mbarbin’s CR I will hate the fact that I have to read a tutorial on that docusaurus website rather than an odig doc crs away, another one is the documentation of js_of_ocaml which I always have to consult on the ocsigen website).
So personally I think it’s a waste of time of odoc’s scarce ressources to multiply the half-baked backends and/or focus on this rather than having an excellent odoc system that provides an integrated and consistent documentation experience for programming in OCaml.
That’s an interesting perspective which I hadn’t considered. This input gave me an idea for some exploration of better compatibility between the tools (very prospective and may not make sense). Tracked by Improve compatibility with odig/odoc-sites · Issue #6 · mbarbin/doc-experiment-docusaurus · GitHub
It may not indeed. Documentation usability is very sensitive to the context in which it is projected [0]. Things like will there be a navigation menu that allows me to access that bit while I’m reading that bit etc.
So unless you manage to find a good scheme that caters both for your website presentation and the way it’s going to be presented by the odoc system you may end up crippling the experience of one or the other.
Not to mention that you will have wasted a lot of your time devising the compatibility system, make sure the experience is good on both – or worse only care about the one you use. None of which will likely help with these “This part of the documentation is currently empty.” that I’m reading all over the website :–)
[0]
A good example of that is ocaml.org insistence of using the README of packages as the landing page of package docs. Since those readmes are nowadays taken and tailored to be the homepage of the code hosting plateform the project is hosted on, they make little sense on ocaml.org.
The amount of repeated unuseful textual cruft I and needless information I need to sift through to get to the meat of a package’s docs on ocaml.org is a pure waste of my time. Emphasis is put on the wrong bits and in general the docs are lost in sea of distracting navigation elements which completely hinder proper package doc navigation (e.g. the confusing global fat footer quicking in at the end doc pages) and focused reading .