mdx

Overview

Mdx is a tool for executing code blocks inside of markdown. It can be used to improve documentation workflows and write tests. Documentation struggles from becoming out-dated fairly quickly or just being incorrect given it is usually typed by a programmer into something like markdown.

The unit tests workflow discusses how you can use mdx to write tests for things like command-line tools.

Dune Integration

Mdx plays nicely (although still somewhat experimentally with dune). Mdx stanzas can specify the core parts to getting Mdx working with a library:

• files - specify which files mdx should check for you
• packages - detail the dependencies your code blocks have
• preludes - files to run before anything else, useful for automatically opening packages like Core

In the Wild

The excellent book for learning OCaml, Real World OCaml, uses mdx extensively to automate their book and ensure the code snippets included within it are correct. Code is written in an examples directory and mdx keeps the examples and embedded code blocks in the content of the book synchronised.