Addons

Mr.Docs is customised through addons: directory trees that hold custom Handlebars templates, helper scripts and extension scripts. This page describes addons as a whole; what goes in each subdirectory is covered on Generators and Extensions.

Default and replacement addons

Mr.Docs ships a built-in addon at share/mrdocs/addons/. It contains the default Handlebars templates, helpers and any baseline scripts.

The addons configuration option replaces it:

addons: /path/to/custom/addons

The replacement is wholesale: your addon should provide everything Mr.Docs needs for the generators you intend to use.

Supplemental addons

The more common pattern is to layer a small addon on top of the built-in one rather than replace it entirely. That is what addons-supplemental is for:

addons-supplemental:
  - addons
  - /path/to/another

Each supplemental addon is layered on top of the base addon in the order listed.

Layout

<addons>/
|-- generator/
|   |-- common/{partials,helpers}/        # shared across output formats
|   `-- <fmt>/{layouts,partials,helpers}/ # per-format (html, adoc, ...)
`-- extensions/
    |-- *.js
    `-- *.lua

  • generator/ — Handlebars templates and helpers for the output stage. Detailed in Generators.

  • extensions/ — scripts that run after corpus construction and can mutate symbols before any generator sees them. Detailed in Extensions.

Discovery

Mr.Docs visits addons in this order:

  1. The base addon (the built-in share/mrdocs/addons/ or whatever addons points at).

  2. Each entry of addons-supplemental, in the order listed.

For templates and helpers, the rule is last wins: a file in a supplemental addon overrides a same-named file in earlier addons. For extensions, every script across every addon is collected and run in alphabetical order by full path; there is no override semantic.