Pipeline Extensions

Mr.Docs is customized in three ways, and they differ in where they plug in:

  • Pipeline extensions register corpus transforms and generators. They are written in Lua, JavaScript or C++ (a plugin), and live under extensions/ of an addon root. The order in which they load is stable for the same set of addon directories, but an extension must not rely on it.

  • Template extensions change what a handlebars generator renders. Handlebars extensions customize handlebars templates, partials and helpers, and the data-driven generators built from them. They live under addons/generator/<name>/ and belong with the generators.

  • Integrations run Mr.Docs from somewhere else: Antora extensions for an Antora build, or a C++ program that uses Mr.Docs as a library.

This section covers the first kind. A pipeline extension joins the run itself, instead of changing what an existing generator renders. It does one of two things, and it is written in Lua, JavaScript or C++:

  • A corpus transform rewrites metadata across many symbols between extraction and rendering, so every generator sees the change.

  • A programmatic generator owns the whole emit and writes whatever files it wants.

The languages are Lua and JavaScript, the two script engines built into Mr.Docs, and C++, in a shared library that Mr.Docs loads as it starts up. A single extension can register both a transform and a generator.