feat: support plugins

[gennaroprota]

This PR adds support for plugins, i.e. shared libraries written in C++ that can be written and compiled without needing Clang/LLVM headers.

Changes

• Source:
  • A public header, mrdocs/Plugin.hpp. It says what a plugin has to export (an entry point, the interface version, a toolchain tag) and what MrDocs passes in (PluginContext). It also provides MRDOCS_PLUGIN_MAIN, a macro that writes those exported functions for the plugin author.
  • The loader. It finds the libraries in each addon root, in order, checks the version and the toolchain, and calls the entry point.
  • One call to the loader while the tool starts up, before any generator is looked up by id.
  • Export attributes. They now expand to a real attribute when MrDocs itself is built. They also move to a header of their own, because Platform.hpp includes Assert.hpp before it could define them.
• Tests: discovery unit tests, a stats example plugin run by ctest, and a link test under tests/plugin-api.
• Build:
  • The mrdocs target sets ENABLE_EXPORTS. It also lists, on its interface, the include directories and compile options a plugin needs.
  • The example plugin and the link test are built as module libraries. The example is built into an addon root that its own test passes to MrDocs.

Testing

Each test checks something the others cannot.

• The discovery unit tests check which files are loaded, in what order, and that a library reachable through two roots is loaded once. Those rules are part of the documented behavior, so they should not change by accident.
• The stats example runs MrDocs with a configuration that asks for generator: stats. That name only exists if the plugin was found, loaded, and installed its generator, so the test fails if any step in that chain breaks.
• The link test checks that the API a plugin uses is really exported. A plugin compiles its own copy of every inline and template member, and those copies call functions that live in the tool and need an export attribute. If one of them is missing, the plugin does not link, and no other test would notice.

Writing the link test found a real problem. The comparison operators of the symbol kinds were not exported, so a plugin that sorts members could not link. The first commit fixes that.

The two ctest tests run in suites that CI already runs. The link test has no ctest entry, because it does not need one: it is a library, and a missing symbol makes the build fail. So CI needs no change.

The link test only detects a missing export on Windows, where a plugin gets its symbols from the tool's export table. On Linux and macOS, it still checks that the public headers compile the way a plugin compiles them, and that such a library links against the executable.

One thing is not tested: the cases where the loader refuses a plugin, that is, a wrong interface version, a wrong toolchain, or a missing entry point. Testing those needs a library built the wrong way on purpose.

Documentation

A new Plugins page under Extensions covers where plugins live, the entry point, the generator, and how to build one. Its code comes from the example through tag includes, so the page cannot drift from something that compiles. The plugins directory that ships with MrDocs gets a README saying what belongs in it.

Closes #58.

[github-actions]

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🛠️ Source	57%	1066	1001	65	31	6	25	-	-
📦 Other	13%	242	240	2	5	3	2	-	-
🧪 Unit Tests	11%	210	210	-	1	1	-	-	-
📚 Examples	10%	195	195	-	5	4	1	-	-
📄 Docs	7%	134	124	10	3	1	2	-	-
🏗️ Build	1%	13	13	-	2	-	2	-	-
Total	100%	1860	1783	77	47	15	32	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• include/mrdocs/Plugin.hpp (Source): 295 lines Δ (+295 / -0)
• src/mrdocs/Support/PluginLoader.cpp (Source): 263 lines Δ (+263 / -0)
• tests/unit/Support/PluginLoader.cpp (Unit Tests): 210 lines Δ (+210 / -0)

Generated by 🚫 dangerJS against 9460dee

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.12%. Comparing base (e31308f) to head (9460dee).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1256   +/-   ##
========================================
  Coverage    83.12%   83.12%           
========================================
  Files           35       35           
  Lines         3662     3662           
  Branches       844      844           
========================================
  Hits          3044     3044           
  Misses         410      410           
  Partials       208      208           

Flag	Coverage Δ
bootstrap	83.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1256.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-08-21 10:34:00 UTC

[alandefreitas]

I think the doc preview isn't working. We need to debug that for this PR. In any case, I read the adoc file, and I'm not sure I understand the user workflow. As far as I understand, the user would need an mrdocs installation and a way to link whatever they need to their own project to write a plugin. And tests would have to emulate that. This can't be tested from the inside before mrdocs is installed.

[gennaroprota]

It seems that the doc preview stopped working around 5-6 June 2026.

About the user workflow, your reading is right: the author needs an install. But I'm not sure what you mean by "can't be tested from the inside"; isn't that what tests/plugin-api does?

However, I noticed that the docs prescribe find_package(mrdocs REQUIRED CONFIG) in two places, which fails for everyone. The generated config expands @DUKTAPE_PACKAGE_NAME@, which is now undefined, into a bare find_dependency(), which is a hard CMake error, so both sets of instructions have been broken the whole time. find_dependency(fmt) is dead too: nothing in the project links fmt any more. That leaves LLVM and Clang, legitimate for mrdocs-core consumers, but not for plugin authors. I will fix the config here, and add an install-and-consume test that builds a plugin against a staged prefix alone.

[alandefreitas]

I will fix the config here and add an install-and-consume test that builds a plugin against a staged prefix alone.

Please hang on a little bit then, because I've been already working on precisely this issue for the last two weeks. My fork is nothing but CI tests for test/cmake-package lately.

[alandefreitas]

Done: #1262

[gennaroprota]

Great!