Plugins case study: mdBook preprocessors

Summary

mdBook is a tool for easily creating books out of Markdown files. It's very popular in the Rust ecosystem, where it's used (among other things) to publish the official Rust book. mdBook has a simple yet effective plugin mechanism that can be used to modify the book output in arbitrary ways, using any programming language or tool. This post describes the mechanism and how it aligns with the fundamental concepts of plugin infrastructures. mdBook preprocessors mdBook's architecture is pretty simple: your contents go into a directory tree of Markdown files. mdBook then renders these into a book, with one file per chapter. The book's output is HTML by default, but mdBook supports other outputs like PDF. The preprocessor mechanism lets us register an arbitrary program that runs on the book's source after it's loaded from Markdown files; this program can modify the book's contents in any way it wishes before it all gets sent to the renderer for generating output. The official documentation explains this process very well. Sample plugin I rewrote my classical "nacrissist" plugin for mdBook; the code is available here. In fact, there are two renditions of the same plugin there: One in Python, to demonstrate how mdBook can invoke preprocessors written in any programming language. One in Rust, to demonstrate how mdBook exposes an application API to plugins written in Rust (since mdBook is itself written in Rust). Fundamental plugin concepts in this case study Let's see how this case study of mdBook preprocessors measures against the Fundamental plugin concepts that were covered several times on this blog. Discovery Discovery in mdBook is very explicit. For every plugin we want mdBook to use, it has to be listed in the project's book.toml configuration file. For example, in the code sample for this post, the Python narcissist plugin is noted in book.toml as follows: [preprocessor.narcissistpy] command = "python3 ../preprocessor-python-narcissist/narcissist.py" Each preprocessor...