Mdx
Last Updated: 14, September 2020 at 14:06:20
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 youpackages- detail the dependencies your code blocks havepreludes- files to run before anything else, useful for automatically opening packages likeCore
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.
Related Workflows
Testing
- Setting up Continuous Integration - Add CI to your project using Github Actions
Publishing
- Documenting your Project - Write maintainable and useful documentation for your library