Plugins case study: mdBook preprocessors

"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'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."

mdBook converts a directory tree of Markdown files into a book, rendering one output file per chapter. The default output format is HTML, with support for alternatives such as PDF. A plugin system supports preprocessors and renderers. Preprocessors run on the loaded book source and can modify contents arbitrarily before the renderer generates output. Renderers (also called backends) receive the same input and may produce any output, with the default backend emitting HTML. Plugins can be implemented in any programming language; examples exist in Python and Rust. A Rust API enables native plugins that integrate closely with mdBook. This architecture enables flexible, language-agnostic extension of the book generation pipeline for customized transformations and outputs.

Read at Thegreenplace