This is a small command line script to convert .mld files using odoc syntax
to Markdown. Essentially, it does the reverse of md2mld.
When writing OCaml documentation, I find writing documentation in an .mld file more powerful
as it allows linking to values easily. However, I often want to have the main index.mld page
also available as a README.md to be accessible directly from Github, without having
to go to the documentation website. This script enables generating that README.md
from the index.mld directly.
This is a naive and quickly put together script, so it is probably rough around the edges.
Complex structures may not be rendered as well as you'll expect. In particular
Since the powerful linking features of odoc cannot be replicated in markdown,
most links to values are just replaced with inline code (i.e. {!mylink} becomes `mylink`, and
{{!mylink}alt-text} becomes alt-text).
mld2md tries to be smart with header links: if you have a header {0:id text} and a link {!id} or {{!id}alt-text}
in the same file, it should generate [text](#id) or [alt-text](#id) for the link.
The script can be called directly from the command line:
$ md2mld index.mld > README.md--strip-id: remove custom heading ids. Using it renders{0:id title}as# titleand not# title {#id}as the latter is not standard markdown.