<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="3.8.7">Jekyll</generator><link href="http://cppalliance.org/feed.xml" rel="self" type="application/atom+xml" /><link href="http://cppalliance.org/" rel="alternate" type="text/html" /><updated>2026-05-12T01:20:16+00:00</updated><id>http://cppalliance.org/feed.xml</id><title type="html">The C++ Alliance</title><subtitle>The C++ Alliance is dedicated to helping the C++ programming language evolve. We see it developing as an ecosystem of open source libraries and as a growing community of those who contribute to those libraries..</subtitle><entry><title type="html">MrDocs in the Wild</title><link href="http://cppalliance.org/alan/2026/04/24/Alan.html" rel="alternate" type="text/html" title="MrDocs in the Wild" /><published>2026-04-24T00:00:00+00:00</published><updated>2026-04-24T00:00:00+00:00</updated><id>http://cppalliance.org/alan/2026/04/24/Alan</id><content type="html" xml:base="http://cppalliance.org/alan/2026/04/24/Alan.html">&lt;p&gt;The questions changed. For a long time, people asked about &lt;a href=&quot;https://www.mrdocs.com&quot;&gt;MrDocs&lt;/a&gt; in the abstract: what formats will it support, how will it handle templates, when will it be ready. Then, gradually, the questions became specific. &lt;a href=&quot;https://github.com/jll63&quot;&gt;Jean-Louis Leroy&lt;/a&gt;, the author of &lt;strong&gt;&lt;a href=&quot;https://github.com/boostorg/openmethod&quot;&gt;Boost.OpenMethod&lt;/a&gt;&lt;/strong&gt;, became one of our most active sources of feedback. His library exercises corners of C++ that most projects never touch, which means MrDocs gets tested in ways we would not have anticipated. He wanted to know why his template specializations were not sorted correctly. He wanted &lt;strong&gt;macro support&lt;/strong&gt; because Boost libraries rely heavily on macros. He hit a &lt;strong&gt;crash&lt;/strong&gt; when his doc comments contained HTML tables. These are not theoretical questions about a tool that might exist someday. These are questions from someone who already generated documentation with MrDocs and needs it to work better.&lt;/p&gt;

&lt;p&gt;In our &lt;a href=&quot;/alan/2025/10/28/Alan.html&quot;&gt;previous post&lt;/a&gt;, we described MrDocs transitioning from prototype to product. This post is about what happened when MrDocs went into the wild.&lt;/p&gt;

&lt;!-- prettier-ignore --&gt;

&lt;ul id=&quot;markdown-toc&quot;&gt;

&lt;li&gt;&lt;a href=&quot;#real-projects-real-problems&quot; id=&quot;markdown-toc-real-projects-real-problems&quot;&gt;Real Projects, Real Problems&lt;/a&gt; &lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;#the-demo-page&quot; id=&quot;markdown-toc-the-demo-page&quot;&gt;The Demo Page&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#breadcrumbs-without-a-navigation-file&quot; id=&quot;markdown-toc-breadcrumbs-without-a-navigation-file&quot;&gt;Breadcrumbs Without a Navigation File&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#coordinating-two-independent-extensions&quot; id=&quot;markdown-toc-coordinating-two-independent-extensions&quot;&gt;Coordinating Two Independent Extensions&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#edge-cases-in-the-wild&quot; id=&quot;markdown-toc-edge-cases-in-the-wild&quot;&gt;Edge Cases in the Wild&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#rendering-and-output&quot; id=&quot;markdown-toc-rendering-and-output&quot;&gt;Rendering and Output&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#under-the-hood&quot; id=&quot;markdown-toc-under-the-hood&quot;&gt;Under the Hood&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#the-mrdocs-website&quot; id=&quot;markdown-toc-the-mrdocs-website&quot;&gt;The MrDocs Website&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#exploring-the-unknowns&quot; id=&quot;markdown-toc-exploring-the-unknowns&quot;&gt;Exploring the Unknowns&lt;/a&gt; &lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;#reflection-replacing-boilerplate-with-introspection&quot; id=&quot;markdown-toc-reflection-replacing-boilerplate-with-introspection&quot;&gt;Reflection: Replacing Boilerplate with Introspection&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#first-steps-toward-extensions&quot; id=&quot;markdown-toc-first-steps-toward-extensions&quot;&gt;First Steps Toward Extensions&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#why-we-discarded-mrdocs-as-compiler&quot; id=&quot;markdown-toc-why-we-discarded-mrdocs-as-compiler&quot;&gt;Why We Discarded MrDocs-as-Compiler&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#contributor-experience&quot; id=&quot;markdown-toc-contributor-experience&quot;&gt;Contributor Experience&lt;/a&gt; &lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;#automating-pr-reviews&quot; id=&quot;markdown-toc-automating-pr-reviews&quot;&gt;Automating PR Reviews&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#ci-infrastructure&quot; id=&quot;markdown-toc-ci-infrastructure&quot;&gt;CI Infrastructure&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#test-infrastructure&quot; id=&quot;markdown-toc-test-infrastructure&quot;&gt;Test Infrastructure&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#acknowledgments-and-reflections&quot; id=&quot;markdown-toc-acknowledgments-and-reflections&quot;&gt;Acknowledgments and Reflections&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;h1 id=&quot;real-projects-real-problems&quot;&gt;Real Projects, Real Problems&lt;/h1&gt;

&lt;div class=&quot;mermaid&quot;&gt;

%%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#e4eee8&quot;, &quot;primaryBorderColor&quot;: &quot;#affbd6&quot;, &quot;primaryTextColor&quot;: &quot;#000000&quot;, &quot;lineColor&quot;: &quot;#baf9d9&quot;, &quot;secondaryColor&quot;: &quot;#f0eae4&quot;, &quot;tertiaryColor&quot;: &quot;#ebeaf4&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%%

mindmap

root((Feedback))

First impressions

Unstyled demos

Custom stylesheets

Navigation

Orphaned pages

Breadcrumbs

AST edge cases

Parameter packs

Friend targets

Detail namespaces

Rendering

Description ordering

Code blocks

Anchor links

Runtime

JS engine switch

Compiler fallback

&lt;/div&gt;

&lt;h2 id=&quot;the-demo-page&quot;&gt;The Demo Page&lt;/h2&gt;

&lt;p&gt;Right after the &lt;a href=&quot;/alan/2025/10/28/Alan.html&quot;&gt;previous post&lt;/a&gt;, where we announced the MVP and encouraged people to try MrDocs, we noticed the &lt;strong&gt;&lt;a href=&quot;https://www.mrdocs.com/demos&quot;&gt;demos page&lt;/a&gt;&lt;/strong&gt; was not doing us any favors. Someone shared MrDocs on a developer community and the website started getting traffic. The landing page looked polished, but visitors clicked through to the demos and saw raw, unstyled HTML: no fonts, no spacing, no colors. The HTML generator produced correct semantic markup, and that is technically the point: users are supposed to customize the output with their own stylesheets. But on the demos page, there was no stylesheet at all, and the result looked broken rather than customizable.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1122&quot;&gt;custom stylesheet system&lt;/a&gt;&lt;/strong&gt; added five configuration options (&lt;code&gt;stylesheets&lt;/code&gt;, &lt;code&gt;linkcss&lt;/code&gt;, &lt;code&gt;copycss&lt;/code&gt;, &lt;code&gt;no-default-styles&lt;/code&gt;, &lt;code&gt;stylesdir&lt;/code&gt;) so projects can match their own branding. A bundled default CSS now ships with MrDocs, and it was &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1101&quot;&gt;refined&lt;/a&gt; to remove gradients in favor of solid, readable backgrounds.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Stylesheet commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/5fe30c1&quot;&gt;5fe30c1&lt;/a&gt; feat: custom stylesheets&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/33d985c&quot;&gt;33d985c&lt;/a&gt; chore: version is 0.8.0&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;breadcrumbs-without-a-navigation-file&quot;&gt;Breadcrumbs Without a Navigation File&lt;/h2&gt;

&lt;p&gt;MrDocs generates &lt;strong&gt;thousands of reference pages&lt;/strong&gt;, one per C++ symbol. We maintain an &lt;a href=&quot;https://antora.org/&quot;&gt;Antora&lt;/a&gt; extension, the &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension&quot;&gt;antora-cpp-reference-extension&lt;/a&gt;&lt;/strong&gt;, that integrates these pages into Antora-based documentation sites. But the generated pages end up orphaned from the navigation tree. Users found the navigation confusing: clicking on “boost” in the breadcrumb did not go where expected, and reference pages had no trail showing where they belonged in the hierarchy.&lt;/p&gt;

&lt;p&gt;The obvious fix would be to list every page in Antora’s &lt;code&gt;nav.adoc&lt;/code&gt;, but maintaining a navigation file with thousands of entries that changes every time a symbol is added or removed is not practical. Worse, Antora renders the navigation file in the &lt;strong&gt;sidebar&lt;/strong&gt;, so listing every reference page would flood the UI with thousands of entries. We discussed the problem extensively with the &lt;a href=&quot;https://antora.org/&quot;&gt;Antora&lt;/a&gt; maintainer on the &lt;a href=&quot;https://antora.zulipchat.com/&quot;&gt;Antora community chat&lt;/a&gt;. His position was clear: Antora was designed so that pages must be in the navigation file. Programmatic editing of navigation is not supported.&lt;/p&gt;

&lt;p&gt;That was not acceptable for us. We needed breadcrumbs that work for thousands of generated pages without polluting the sidebar or requiring a hand-maintained navigation file. The Antora author’s position was reasonable from his perspective (Antora is a general-purpose documentation tool, not a reference generator), but our use case was fundamentally different from what Antora was designed for.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension&quot;&gt;antora-cpp-reference-extension&lt;/a&gt;&lt;/strong&gt; now &lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/ae95eb2&quot;&gt;builds breadcrumbs independently&lt;/a&gt; from the navigation file. MrDocs generates reference pages in a directory structure that mirrors the C++ namespace hierarchy (&lt;code&gt;boost/urls/segments_view.adoc&lt;/code&gt; lives inside &lt;code&gt;boost/urls/&lt;/code&gt;). The extension uses this structure to reconstruct the breadcrumb trail: each directory maps to a namespace, and the page title (which is the symbol name) becomes the last breadcrumb entry. The result reads naturally: &lt;strong&gt;Reference &amp;gt; boost &amp;gt; urls &amp;gt; segments_view&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Zero changes to the nav file. The sidebar stays clean. Breadcrumbs appear automatically and update when symbols are added or removed.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Breadcrumb and reference extension commits&lt;/summary&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension&quot;&gt;antora-cpp-reference-extension&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/ae95eb2&quot;&gt;ae95eb2&lt;/a&gt; feat: synthesize reference breadcrumbs without nav files&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/10a4019&quot;&gt;10a4019&lt;/a&gt; feat: add auto base URL detection&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/6a6c08b&quot;&gt;6a6c08b&lt;/a&gt; docs: auto-base-url option&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/4f7c79f&quot;&gt;4f7c79f&lt;/a&gt; refactor: enhance release asset validation&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;coordinating-two-independent-extensions&quot;&gt;Coordinating Two Independent Extensions&lt;/h2&gt;

&lt;p&gt;The &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension&quot;&gt;antora-cpp-reference-extension&lt;/a&gt;&lt;/strong&gt; generates reference pages and breadcrumbs. The &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-tagfiles-extension&quot;&gt;antora-cpp-tagfiles-extension&lt;/a&gt;&lt;/strong&gt; resolves cross-library symbol links (so a reference to &lt;code&gt;boost::system::error_code&lt;/code&gt; in Boost.URL’s docs links to the correct page in Boost.System’s docs). These are &lt;strong&gt;two independent Antora extensions&lt;/strong&gt; running as separate jobs.&lt;/p&gt;

&lt;p&gt;The problem was that the reference extension generates &lt;strong&gt;tagfiles&lt;/strong&gt; as a side effect of producing reference pages, and the tagfiles extension needs the &lt;strong&gt;most recent version&lt;/strong&gt; of those tagfiles to resolve links correctly. MrDocs changes the tagfiles every time the corpus changes. Manually keeping them in sync was not sustainable: committing tagfiles to the repository meant they were always stale by the time the next build ran.&lt;/p&gt;

&lt;p&gt;We made the extensions &lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/6e8ffcb&quot;&gt;coordinate directly&lt;/a&gt;. The reference extension now hands its tagfile to the tagfiles extension at build time, so the links always reflect the current state of the documentation. The reference extension also gained &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/10a4019&quot;&gt;auto base URL detection&lt;/a&gt;&lt;/strong&gt;, removing the need for manual path configuration when switching between development and production builds.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Extension coordination commits&lt;/summary&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension&quot;&gt;antora-cpp-reference-extension&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/6e8ffcb&quot;&gt;6e8ffcb&lt;/a&gt; feat: antora-cpp-tagfiles-extension coordination&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-reference-extension/commit/8f12576&quot;&gt;8f12576&lt;/a&gt; chore: version is 0.1.0&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-tagfiles-extension&quot;&gt;antora-cpp-tagfiles-extension&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-tagfiles-extension/commit/98eba40&quot;&gt;98eba40&lt;/a&gt; feat: antora-cpp-reference-extension coordination&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-tagfiles-extension/commit/5a1723c&quot;&gt;5a1723c&lt;/a&gt; feat: add global log level control for missing symbols&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/antora-cpp-tagfiles-extension/commit/453f01b&quot;&gt;453f01b&lt;/a&gt; chore: version is 0.1.0&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;edge-cases-in-the-wild&quot;&gt;Edge Cases in the Wild&lt;/h2&gt;

&lt;p&gt;As more libraries adopted MrDocs, edge cases in C++ symbol extraction surfaced. &lt;a href=&quot;https://github.com/boostorg/beast&quot;&gt;Boost.Beast&lt;/a&gt; exposed a &lt;strong&gt;duplicate ellipsis&lt;/strong&gt; in parameter pack rendering (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1108&quot;&gt;#1108&lt;/a&gt;, &lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1129&quot;&gt;#1129&lt;/a&gt;):&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Before:&lt;/strong&gt; &lt;code&gt;T&amp;amp; emplace(Args...&amp;amp;&amp;amp;... args)&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;After:&lt;/strong&gt; &lt;code&gt;T&amp;amp; emplace(Args&amp;amp;&amp;amp;... args)&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href=&quot;https://github.com/boostorg/openmethod&quot;&gt;Boost.OpenMethod&lt;/a&gt; revealed that &lt;strong&gt;friend targets&lt;/strong&gt; were not resolving correctly. &lt;a href=&quot;https://github.com/cppalliance/buffers&quot;&gt;Boost.Buffers&lt;/a&gt; uncovered a problem with &lt;strong&gt;detail namespaces&lt;/strong&gt;: when a class inherits from a base in a hidden namespace, the inherited members appeared in the documentation but their doc comments were lost (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1107&quot;&gt;#1107&lt;/a&gt;). We &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1109&quot;&gt;fixed this&lt;/a&gt; so derived classes inherit documentation from hidden bases.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unnamed structs&lt;/strong&gt; also sparked an extended design discussion. When C++ code declares &lt;code&gt;constexpr struct {} f{};&lt;/code&gt;, MrDocs needs a &lt;strong&gt;stable, unique name&lt;/strong&gt; for hyperlinks. The team established a collaborative design process using shared documents, with &lt;a href=&quot;https://github.com/pdimov&quot;&gt;Peter Dimov&lt;/a&gt; contributing an insight about C compatibility (&lt;code&gt;typedef struct {} T;&lt;/code&gt; makes the struct named in C++).&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;AST and metadata commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/c85be75&quot;&gt;c85be75&lt;/a&gt; fix: remove duplicate ellipsis in parameter pack expansion&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/c3dbded&quot;&gt;c3dbded&lt;/a&gt; fix(ast): prevent TU parent from including unmatched globals&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/76b7b43&quot;&gt;76b7b43&lt;/a&gt; fix(ast): canonicalize friend targets&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/05f5852&quot;&gt;05f5852&lt;/a&gt; fix(metadata): copy impl-defined base docs&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/35cf1f6&quot;&gt;35cf1f6&lt;/a&gt; fix: UsingSymbol is SymbolParent&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/c406d57&quot;&gt;c406d57&lt;/a&gt; fix: preserve extraction mode when copying members from derived classes&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/4e7ef04&quot;&gt;4e7ef04&lt;/a&gt; fix: prevent infinite recursion when extracting non-regular base class&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/0a69301&quot;&gt;0a69301&lt;/a&gt; fix: extract and fix some special member function helpers&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;rendering-and-output&quot;&gt;Rendering and Output&lt;/h2&gt;

&lt;p&gt;Users noticed that the &lt;strong&gt;manual description&lt;/strong&gt; of a symbol was buried below long member tables (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1105&quot;&gt;#1105&lt;/a&gt;). On a class with many members, you had to scroll past the entire member listing before finding the author’s explanation of what the class does. We moved the description to appear &lt;strong&gt;immediately after the synopsis&lt;/strong&gt;, matching what &lt;a href=&quot;https://en.cppreference.com/&quot;&gt;cppreference&lt;/a&gt; does.&lt;/p&gt;

&lt;p&gt;Other rendering issues included HTML code blocks not wrapped in &lt;code&gt;&amp;lt;pre&amp;gt;&lt;/code&gt; tags, &lt;strong&gt;anchor links&lt;/strong&gt; appearing when the wrapper element was missing, and the Handlebars template engine accumulating &lt;strong&gt;special name re-mappings&lt;/strong&gt; that conflated different symbols.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Rendering and output commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/d90eae6&quot;&gt;d90eae6&lt;/a&gt; fix: hide anchor links when wrapper is not included&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/92491de&quot;&gt;92491de&lt;/a&gt; fix: manual description comes before member lists&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/58bf524&quot;&gt;58bf524&lt;/a&gt; fix: remove all special name re-mappings for Handlebars&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/2a75692&quot;&gt;2a75692&lt;/a&gt; fix: HTML code blocks not wrapped in pre tags&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/1ebff32&quot;&gt;1ebff32&lt;/a&gt; fix: bottomUpTraverse() skips ListBlock items&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/7b118b1&quot;&gt;7b118b1&lt;/a&gt; fix: missing @return command in doc comment&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;under-the-hood&quot;&gt;Under the Hood&lt;/h2&gt;

&lt;p&gt;We fixed a &lt;strong&gt;compiler fallback&lt;/strong&gt; issue where MrDocs failed when the compilation database referenced a compiler that was not available on the current machine, and corrected &lt;strong&gt;sanitizer flag propagation&lt;/strong&gt; so that UBSan and TSan do not unnecessarily propagate to dependency builds.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Build and toolchain commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/235f5c8&quot;&gt;235f5c8&lt;/a&gt; fix: fall back to system compilers when database compiler is unavailable&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/f320581&quot;&gt;f320581&lt;/a&gt; fix: don’t pass sanitizer to dependency builds for UBSan/TSan&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;the-mrdocs-website&quot;&gt;The MrDocs Website&lt;/h2&gt;

&lt;p&gt;While we were fixing the generated output, &lt;strong&gt;&lt;a href=&quot;https://github.com/rbbeeston&quot;&gt;Robert Beeston&lt;/a&gt;&lt;/strong&gt; and &lt;strong&gt;&lt;a href=&quot;https://github.com/julioest&quot;&gt;Julio Estrada&lt;/a&gt;&lt;/strong&gt; were redesigning the &lt;a href=&quot;https://www.mrdocs.com&quot;&gt;MrDocs website&lt;/a&gt;. Robert led the design direction, working with a team to develop a visual identity that balances a distinctive retro aesthetic with modern readability, including a dark theme. Julio handled the implementation: &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1032&quot;&gt;mobile-responsive layout&lt;/a&gt;, &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1050&quot;&gt;UI styling improvements&lt;/a&gt;, &lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/86ce271&quot;&gt;cleaner backgrounds and styles&lt;/a&gt;, &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1075&quot;&gt;Open Graph and Twitter meta tags&lt;/a&gt; for social sharing, and a &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1033&quot;&gt;close button for the docs navigation&lt;/a&gt; on smaller screens.&lt;/p&gt;

&lt;p&gt;For a documentation tool, the website is the first thing potential users see. Having a polished, memorable landing page matters more than it might for other kinds of projects.&lt;/p&gt;

&lt;h1 id=&quot;exploring-the-unknowns&quot;&gt;Exploring the Unknowns&lt;/h1&gt;

&lt;p&gt;The team made a deliberate choice: instead of following a &lt;strong&gt;traditional feature roadmap&lt;/strong&gt;, we would focus on &lt;strong&gt;areas of uncertainty&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1113&quot;&gt;#1113&lt;/a&gt;). These were &lt;strong&gt;open questions&lt;/strong&gt; that blocked multiple design decisions at once:&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;strong&gt;MrDocs-as-compiler&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1073&quot;&gt;#1073&lt;/a&gt;): should MrDocs emit “object” files for later “linking,” like a compiler?&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Scripting extensions&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1128&quot;&gt;#1128&lt;/a&gt;, &lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/881&quot;&gt;#881&lt;/a&gt;): how should users extend and transform documentation output?&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Plugins&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/58&quot;&gt;#58&lt;/a&gt;, &lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1044&quot;&gt;#1044&lt;/a&gt;): how should third-party code register new generators?&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;JSON-only MrDocs&lt;/strong&gt;: should we add a JSON output format alongside (or replacing) the existing XML structured output?&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Reflection&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1114&quot;&gt;#1114&lt;/a&gt;): how do we reduce the maintenance burden of the growing metadata model?&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Cross-linking&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1072&quot;&gt;#1072&lt;/a&gt;): how do we reference symbols in other libraries?&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;The motivation was practical. Each Boost library that adopted MrDocs had its own needs that could not be met by the core tool alone. &lt;a href=&quot;https://github.com/boostorg/url&quot;&gt;Boost.URL&lt;/a&gt; has &lt;code&gt;implementation_defined&lt;/code&gt; namespaces with internal code that should be hidden or transformed in the documentation. &lt;a href=&quot;https://github.com/cppalliance/capy&quot;&gt;Boost.Capy&lt;/a&gt; has detail types that should be presented as user-facing types. Coroutines are represented as types in the AST but should be documented as functions. We want MrDocs to be smart enough, with project-specific extensions, that library authors do not have to do workarounds in the source code just to get the documentation right.&lt;/p&gt;

&lt;p&gt;Rather than hard-coding solutions for each library, the unknowns framework asked: what general mechanisms would let every library solve its own documentation problems?&lt;/p&gt;

&lt;div class=&quot;mermaid&quot;&gt;

%%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#f7f9ff&quot;, &quot;primaryBorderColor&quot;: &quot;#9aa7e8&quot;, &quot;primaryTextColor&quot;: &quot;#1f2a44&quot;, &quot;lineColor&quot;: &quot;#b4bef2&quot;, &quot;secondaryColor&quot;: &quot;#fbf8ff&quot;, &quot;tertiaryColor&quot;: &quot;#ffffff&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%%

mindmap

root((Unknowns))

Scripting extensions

JS helpers

Lua

Plugins

Generator API

DLL loading

Reflection

Boost.Describe

MrDocs.Describe

Cross-linking

Tagfiles

Antora coordination

JSON-only MrDocs

MrDocs-as-compiler

&lt;/div&gt;

&lt;h2 id=&quot;reflection-replacing-boilerplate-with-introspection&quot;&gt;Reflection: Replacing Boilerplate with Introspection&lt;/h2&gt;

&lt;p&gt;MrDocs models many kinds of C++ symbols: functions, classes, namespaces, enums, typedefs, concepts, and more. Each symbol type has metadata, and every piece of code that touches that metadata had to &lt;strong&gt;enumerate all fields by hand&lt;/strong&gt;. Adding a single field to a symbol type meant updating it in:&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;strong&gt;Schema files&lt;/strong&gt; that describe the metadata format&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Generators&lt;/strong&gt; (HTML, AsciiDoc, XML) that produce the output&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Templates&lt;/strong&gt; that render individual pages&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Operators&lt;/strong&gt; like comparison functions, merge functions (e.g., merging symbols from different translation units when only one is documented), and equality checks&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Documentation&lt;/strong&gt; describing the metadata&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;The code itself&lt;/strong&gt; that populates and transforms the metadata&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;That is roughly &lt;strong&gt;ten to fifteen places&lt;/strong&gt; per field, and missing one caused CI failures that blocked everyone. This was one of the &lt;strong&gt;unknowns&lt;/strong&gt; we identified: how to reduce the maintenance burden as the data model grows. Worse, downstream users who had their own templates and extensions also had to learn about the new fields and update everything accordingly.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/gennaroprota&quot;&gt;Gennaro Prota&lt;/a&gt;&lt;/strong&gt;, with his strong background in generic programming and metaprogramming, took ownership of the reflection problem. The work progressed through several stages:&lt;/p&gt;

&lt;ol&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1130&quot;&gt;Integrate Boost.Describe&lt;/a&gt; into the metadata system, replacing hand-written serialization functions&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1153&quot;&gt;Add &lt;code&gt;$meta.type&lt;/code&gt; and &lt;code&gt;$meta.bases&lt;/code&gt;&lt;/a&gt; to all DOM objects so templates can introspect the corpus&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1151&quot;&gt;Replace the XML generator&lt;/a&gt; with a reflection-based one (no more hand-maintained XML output)&lt;/li&gt;

&lt;li&gt;Build a &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1171&quot;&gt;custom reflection system (MrDocs.Describe)&lt;/a&gt; tailored to our needs&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1177&quot;&gt;Replace per-type operators&lt;/a&gt; with a single generic template&lt;/li&gt;

&lt;/ol&gt;

&lt;p&gt;The result &lt;strong&gt;eliminated the second step entirely&lt;/strong&gt;: adding a new field to a symbol type no longer requires touching ten other files. The description drives everything, and the serialization, comparison, and merge logic derive from it automatically. &lt;a href=&quot;https://www.boost.org/doc/libs/release/libs/describe/&quot;&gt;Boost.Describe&lt;/a&gt; and &lt;a href=&quot;https://www.boost.org/doc/libs/release/libs/mp11/&quot;&gt;Boost.Mp11&lt;/a&gt; are private dependencies that do not appear in public headers.&lt;/p&gt;

&lt;p&gt;Along the way, Gennaro also added &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1163&quot;&gt;function object support&lt;/a&gt;&lt;/strong&gt;, fixed &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1157&quot;&gt;Markdown inline formatting&lt;/a&gt;&lt;/strong&gt; and &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1173&quot;&gt;missing dependent array bounds&lt;/a&gt;&lt;/strong&gt;.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Reflection and metadata commits&lt;/summary&gt;

&lt;p&gt;&lt;strong&gt;Reflection (Gennaro Prota)&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/d490880&quot;&gt;d490880&lt;/a&gt; refactor(metadata): integrate Boost.Describe&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/c4dd89a&quot;&gt;c4dd89a&lt;/a&gt; feat: add $meta.type and $meta.bases to all DOM objects&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/d4a64ef&quot;&gt;d4a64ef&lt;/a&gt; fix: replace the XML generator with a reflection-based one&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/6ce961f&quot;&gt;6ce961f&lt;/a&gt; refactor: add custom reflection facilities (MrDocs.Describe)&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/eb68494&quot;&gt;eb68494&lt;/a&gt; refactor: migrate all reflection consumers to MrDocs.Describe&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/8f5391b&quot;&gt;8f5391b&lt;/a&gt; refactor: replace per-type merge() one-liners with a single generic template&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/e749144&quot;&gt;e749144&lt;/a&gt; feat: make the reflection consumers public&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/1ed76ad&quot;&gt;1ed76ad&lt;/a&gt; refactor: replace most per-type tag_invoke overloads with a single generic template&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/0246935&quot;&gt;0246935&lt;/a&gt; refactor: replace per-type operator==() and operator&amp;lt;=&amp;gt;() with a single generic template&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Features and fixes (Gennaro Prota)&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/93a5032&quot;&gt;93a5032&lt;/a&gt; feat: add function object support&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/f35ebcd&quot;&gt;f35ebcd&lt;/a&gt; fix: rendering of Markdown inline formatting and bullet lists&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/4ae305b&quot;&gt;4ae305b&lt;/a&gt; fix: missing dependent array bounds in the output&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/72fba40&quot;&gt;72fba40&lt;/a&gt; test: add golden tests for a partial class template specialization&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;blockquote&gt;

&lt;p&gt;The reflection work is the foundation for everything that comes next: the extension system, the upcoming Lua scripting, and the metadata transformation pipeline.&lt;/p&gt;

&lt;/blockquote&gt;

&lt;h2 id=&quot;first-steps-toward-extensions&quot;&gt;First Steps Toward Extensions&lt;/h2&gt;

&lt;p&gt;MrDocs supports two extension points: &lt;strong&gt;JavaScript&lt;/strong&gt; for Handlebars template helpers, and &lt;strong&gt;Lua&lt;/strong&gt; for more powerful scripting. The JavaScript engine had been &lt;a href=&quot;https://duktape.org/&quot;&gt;Duktape&lt;/a&gt;, but Duktape is no longer actively maintained and only supports ES5.1. We needed a replacement.&lt;/p&gt;

&lt;p&gt;We evaluated several alternatives (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/881&quot;&gt;#881&lt;/a&gt;):&lt;/p&gt;

&lt;table&gt;

&lt;thead&gt;

&lt;tr&gt;

&lt;th&gt;Engine&lt;/th&gt;

&lt;th&gt;JS Support&lt;/th&gt;

&lt;th&gt;Windows/MSVC&lt;/th&gt;

&lt;th&gt;Size&lt;/th&gt;

&lt;th&gt;License&lt;/th&gt;

&lt;/tr&gt;

&lt;/thead&gt;

&lt;tbody&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/bellard/quickjs&quot;&gt;QuickJS&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;ES2023&lt;/td&gt;

&lt;td&gt;No (clang-cl only)&lt;/td&gt;

&lt;td&gt;~370 KB&lt;/td&gt;

&lt;td&gt;MIT&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/lynx-family/primjs&quot;&gt;PrimJS&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;ES2019&lt;/td&gt;

&lt;td&gt;No (POSIX only)&lt;/td&gt;

&lt;td&gt;~370 KB&lt;/td&gt;

&lt;td&gt;MIT&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://jerryscript.net/&quot;&gt;JerryScript&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;ES5.1 + ES2022 subset&lt;/td&gt;

&lt;td&gt;Yes&lt;/td&gt;

&lt;td&gt;~200 KB&lt;/td&gt;

&lt;td&gt;Apache 2.0&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/Samsung/escargot&quot;&gt;Escargot&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;ES2025 subset&lt;/td&gt;

&lt;td&gt;Yes&lt;/td&gt;

&lt;td&gt;~400-500 KB&lt;/td&gt;

&lt;td&gt;LGPL 2.1&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/ArtifexSoftware/mujs&quot;&gt;MuJS&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;ES5.1&lt;/td&gt;

&lt;td&gt;Yes&lt;/td&gt;

&lt;td&gt;~200-300 KB&lt;/td&gt;

&lt;td&gt;ISC&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/Moddable-OpenSource/moddable&quot;&gt;Moddable XS&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;ES2025 (~99%)&lt;/td&gt;

&lt;td&gt;Yes (via SDK)&lt;/td&gt;

&lt;td&gt;~100-300 KB&lt;/td&gt;

&lt;td&gt;Apache/GPL/LGPL&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/cesanta/mjs&quot;&gt;mJS&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;Restricted ES6&lt;/td&gt;

&lt;td&gt;Yes&lt;/td&gt;

&lt;td&gt;~50-60 KB&lt;/td&gt;

&lt;td&gt;GPL 2.0 / Commercial&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;a href=&quot;https://github.com/cesanta/elk&quot;&gt;Elk&lt;/a&gt;&lt;/td&gt;

&lt;td&gt;Minimal ES6&lt;/td&gt;

&lt;td&gt;Yes&lt;/td&gt;

&lt;td&gt;~20-30 KB&lt;/td&gt;

&lt;td&gt;GPL 2.0 / Commercial&lt;/td&gt;

&lt;/tr&gt;

&lt;/tbody&gt;

&lt;/table&gt;

&lt;p&gt;We first experimented with &lt;strong&gt;QuickJS&lt;/strong&gt;, which had the best ES support. But it requires C11 features like &lt;code&gt;&amp;lt;stdatomic.h&amp;gt;&lt;/code&gt; and &lt;code&gt;__int128&lt;/code&gt; that plain MSVC does not support. On Windows, users would need Clang with the Visual Studio runtime. &lt;strong&gt;PrimJS&lt;/strong&gt; was POSIX-only. We settled on &lt;strong&gt;&lt;a href=&quot;https://jerryscript.net/&quot;&gt;JerryScript&lt;/a&gt;&lt;/strong&gt;: it supports Windows and MSVC natively, has a small footprint (~200 KB), and covers enough of ES2022 for template helpers. Unlike most alternatives in the table, JerryScript was designed from the ground up to be &lt;strong&gt;embedded&lt;/strong&gt; in other applications, which makes it more like &lt;a href=&quot;https://www.lua.org/&quot;&gt;Lua&lt;/a&gt; and less like engines that target browsers or standalone runtimes.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1126&quot;&gt;JavaScript helpers extension&lt;/a&gt;&lt;/strong&gt; was a single commit but a large one: &lt;strong&gt;85 files changed, 4,287 insertions&lt;/strong&gt;. The work included:&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;strong&gt;Replacing Duktape with JerryScript&lt;/strong&gt; across the entire codebase, including build scripts, CMake recipes, and third-party patches&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Rewriting the C++ JavaScript bindings&lt;/strong&gt; (&lt;code&gt;JavaScript.hpp&lt;/code&gt; and &lt;code&gt;JavaScript.cpp&lt;/code&gt;) with shared context lifetime, safer value accessors, and clearer error messages&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;A layered addon system&lt;/strong&gt; where projects provide JavaScript helpers in a directory structure (&lt;code&gt;generator/common/helpers/&lt;/code&gt; for shared helpers, &lt;code&gt;generator/html/helpers/&lt;/code&gt; for format-specific ones). Multiple addon directories can be layered, so a project’s helpers override or extend the defaults.&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Golden tests&lt;/strong&gt; for extension output (&lt;code&gt;js-helper/&lt;/code&gt;, &lt;code&gt;js-helper-layering/&lt;/code&gt;) to verify that helpers produce the expected documentation&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;1,335 lines of new JavaScript binding tests&lt;/strong&gt; covering the engine lifecycle, value conversion, error handling, and helper registration&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;Combined with the &lt;strong&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1139&quot;&gt;public API for registering custom generators&lt;/a&gt;&lt;/strong&gt;, MrDocs now supports customization beyond templates. A library like &lt;a href=&quot;https://develop.capy.cpp.al/capy/reference/boost/capy.html&quot;&gt;Boost.Capy&lt;/a&gt; could write an extension that transforms its coroutine types into function documentation, without any changes to MrDocs itself.&lt;/p&gt;

&lt;div class=&quot;mermaid&quot;&gt;

%%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#f7f9ff&quot;, &quot;primaryBorderColor&quot;: &quot;#9aa7e8&quot;, &quot;primaryTextColor&quot;: &quot;#1f2a44&quot;, &quot;lineColor&quot;: &quot;#b4bef2&quot;, &quot;secondaryColor&quot;: &quot;#fbf8ff&quot;, &quot;tertiaryColor&quot;: &quot;#ffffff&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%%

flowchart LR

A[Clang AST] --&amp;gt; B[Extraction]

B --&amp;gt; C[Corpus]

C --&amp;gt; D[Transformation Extensions]

D --&amp;gt; E[Handlebars Generators]

E --&amp;gt; F[Documentation Templates]

F --&amp;gt; H[HTML / AsciiDoc]

F --&amp;gt; G[Template Extensions]

G --&amp;gt; F

D -.-&amp;gt; I[XML]

&lt;/div&gt;

&lt;p&gt;The vision for extensions has two layers:&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;strong&gt;Transformation extensions&lt;/strong&gt; operate on the corpus between extraction and generation. A library could transform its internal types into the documentation structure it wants. This layer is not yet implemented.&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Template extensions&lt;/strong&gt; (JavaScript helpers) operate inside the Handlebars templates that produce HTML and AsciiDoc output. This is the layer we shipped.&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Lua scripts&lt;/strong&gt; for more powerful scripting in both layers&lt;/li&gt;

&lt;/ul&gt;

&lt;details&gt;

&lt;summary&gt;Extension and generator commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/0f3ecb4&quot;&gt;0f3ecb4&lt;/a&gt; feat: javascript helpers extension (85 files, 4,287 insertions)&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/930a5ea&quot;&gt;930a5ea&lt;/a&gt; fix: jerry_port_context_free wrong signature causes silent corruption&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/8da0930&quot;&gt;8da0930&lt;/a&gt; feat(lib): public API for generator registration&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/788c1ba&quot;&gt;788c1ba&lt;/a&gt; feat(generators): tables for symbols have headers&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;why-we-discarded-mrdocs-as-compiler&quot;&gt;Why We Discarded MrDocs-as-Compiler&lt;/h2&gt;

&lt;p&gt;One unknown we explored and &lt;strong&gt;deliberately discarded&lt;/strong&gt; was &lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1073&quot;&gt;MrDocs-as-compiler&lt;/a&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1073&quot;&gt;#1073&lt;/a&gt;). The idea, proposed by &lt;a href=&quot;https://github.com/pdimov&quot;&gt;Peter Dimov&lt;/a&gt;, was to treat MrDocs like a compiler: emit “object” files per translation unit, then “link” them to produce the final reference. &lt;a href=&quot;https://cmake.org/&quot;&gt;CMake&lt;/a&gt; would invoke MrDocs as if it were &lt;a href=&quot;https://clang.llvm.org/&quot;&gt;Clang&lt;/a&gt;, with identical command-line options.&lt;/p&gt;

&lt;p&gt;We spent time studying tools that work this way: &lt;a href=&quot;https://clang.llvm.org/extra/clang-tidy/&quot;&gt;clang-tidy&lt;/a&gt;, &lt;a href=&quot;https://clang.llvm.org/extra/clang-doc/&quot;&gt;clang-doc&lt;/a&gt;, &lt;a href=&quot;https://include-what-you-use.org/&quot;&gt;include-what-you-use&lt;/a&gt;. What we found is that &lt;strong&gt;tricking CMake into thinking MrDocs is a real compiler&lt;/strong&gt; is not trivial. Every tool that tries this approach ends up needing either a coordinator binary (reimplementing what MrDocs already has) or CMake helper scripts. Both add workflows rather than simplifying them.&lt;/p&gt;

&lt;p&gt;The experience from the Boost ecosystem reinforced this: no Boost project uses any of these compiler-like tools for static analysis, and the reason is complexity. People who find the compilation database workflow too involved are going to be even less inclined to adopt a tool that requires them to pretend to be a compiler. We decided to keep MrDocs as a &lt;strong&gt;single-step tool&lt;/strong&gt; that reads a compilation database and produces output, rather than splitting it into a multi-binary pipeline that would need its own coordination layer.&lt;/p&gt;

&lt;h1 id=&quot;contributor-experience&quot;&gt;Contributor Experience&lt;/h1&gt;

&lt;p&gt;As more people contributed to MrDocs, the gap between “clone the repo” and “submit a useful PR” needed closing. The biggest change was the &lt;strong&gt;&lt;a href=&quot;/alan/2026/04/15/Alan.html&quot;&gt;bootstrap script&lt;/a&gt;&lt;/strong&gt;, which reduced the entire build setup to a single &lt;code&gt;python bootstrap.py&lt;/code&gt; command (covered in a &lt;a href=&quot;/alan/2026/04/15/Alan.html&quot;&gt;separate post&lt;/a&gt;). Beyond the bootstrap, we &lt;strong&gt;split the contributor guide&lt;/strong&gt; into focused sections, added &lt;strong&gt;reference documentation for MrDocs comment syntax&lt;/strong&gt; (so contributors know what &lt;code&gt;@copydoc&lt;/code&gt;, &lt;code&gt;@see&lt;/code&gt;, and other commands do), and created a &lt;strong&gt;&lt;code&gt;run_all_tests&lt;/code&gt; script&lt;/strong&gt; that runs the full test suite locally without needing to understand the CMake test configuration.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Onboarding commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/b103cba&quot;&gt;b103cba&lt;/a&gt; docs(reference): mrdocs comments&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/9b7ec24&quot;&gt;9b7ec24&lt;/a&gt; feat(util): run_all_tests script&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/5902699&quot;&gt;5902699&lt;/a&gt; docs: update packages&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/302f0a6&quot;&gt;302f0a6&lt;/a&gt; docs: split contribute.adoc guide&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;automating-pr-reviews&quot;&gt;Automating PR Reviews&lt;/h2&gt;

&lt;p&gt;MrDocs PRs tend to be &lt;strong&gt;large and hard to review&lt;/strong&gt;. A single PR might touch the AST visitor, the Handlebars templates, the Antora extension, the CI configuration, and hundreds of &lt;strong&gt;golden test files&lt;/strong&gt; (when an intentional change to the output format updates the expected output for every test case). We found ourselves making the same review comments over and over.&lt;/p&gt;

&lt;p&gt;We set up &lt;strong&gt;&lt;a href=&quot;https://danger.systems/js/&quot;&gt;Danger.js&lt;/a&gt;&lt;/strong&gt; to catch these patterns before human reviewers see the PR. The most important check is &lt;strong&gt;detecting when source code changes do not include corresponding tests&lt;/strong&gt;: if someone changes extraction logic but does not update the golden tests, or changes a template without updating the expected output, Danger flags it. Beyond that:&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;strong&gt;Categorizes&lt;/strong&gt; all file changes into scopes (source, tests, golden-tests, docs, CI, build, tooling) and generates a &lt;strong&gt;summary table&lt;/strong&gt; showing churn per scope&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Validates&lt;/strong&gt; commit messages against &lt;a href=&quot;https://www.conventionalcommits.org/&quot;&gt;Conventional Commits&lt;/a&gt; format&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Warns&lt;/strong&gt; when a single commit exceeds &lt;strong&gt;2,000 lines&lt;/strong&gt; of source churn (encouraging smaller, reviewable slices)&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Flags&lt;/strong&gt; mismatched commit types (e.g., a &lt;code&gt;feat:&lt;/code&gt; commit that only touches test files suggests &lt;code&gt;test:&lt;/code&gt; instead)&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Rejects&lt;/strong&gt; PR descriptions under 40 characters&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Ignores&lt;/strong&gt; the test check for refactor-only PRs where the tests are expected to remain unchanged&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;Even when there are no warnings, the &lt;strong&gt;scope summary table&lt;/strong&gt; gives reviewers an immediate sense of what a large PR touches. On a PR that changes 500 lines of source and 3,000 lines of golden tests, the table makes it clear that the bulk of the diff is expected test output, not new logic.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Danger.js commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/6f5f6e9&quot;&gt;6f5f6e9&lt;/a&gt; ci: setup danger.js&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/5429b2e&quot;&gt;5429b2e&lt;/a&gt; ci(danger): align report table and add top-files summary&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/240921d&quot;&gt;240921d&lt;/a&gt; ci(danger): split PR target ci workflows&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/08c46b6&quot;&gt;08c46b6&lt;/a&gt; ci(danger): correct file delta calculation in reports&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/2cfd081&quot;&gt;2cfd081&lt;/a&gt; ci(danger): adjust large commit threshold&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/71845c8&quot;&gt;71845c8&lt;/a&gt; ci(danger): map root files into explicit scopes&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/17b0a57&quot;&gt;17b0a57&lt;/a&gt; ci(danger): ignore test check for refactor-only PRs&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/6481fd3&quot;&gt;6481fd3&lt;/a&gt; ci(danger): simplify CI naming&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/fd7d248&quot;&gt;fd7d248&lt;/a&gt; ci(danger): omit empty sections from report&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/7502961&quot;&gt;7502961&lt;/a&gt; ci(danger): categorize util/bootstrap as build scope&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/57e191e&quot;&gt;57e191e&lt;/a&gt; ci(danger): better markdown format&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;ci-infrastructure&quot;&gt;CI Infrastructure&lt;/h2&gt;

&lt;p&gt;We integrated &lt;strong&gt;&lt;a href=&quot;https://codecov.io/&quot;&gt;Codecov&lt;/a&gt;&lt;/strong&gt; for tracking test coverage across PRs and switched from GCC to &lt;strong&gt;Clang for coverage&lt;/strong&gt; (more accurate AST-based measurement). CI speed was a recurring concern: we &lt;strong&gt;skipped remote documentation generation on PRs&lt;/strong&gt;, &lt;strong&gt;sped up release demos&lt;/strong&gt;, and &lt;strong&gt;skipped long tests&lt;/strong&gt; that were not catching new bugs. LLVM cache keys were &lt;strong&gt;unified&lt;/strong&gt; to avoid redundant builds, and CTest timeouts were increased for sanitizer jobs that run significantly slower. &lt;strong&gt;&lt;a href=&quot;https://github.com/mizvekov&quot;&gt;Matheus Izvekov&lt;/a&gt;&lt;/strong&gt; contributed the &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1144&quot;&gt;Clang coverage switch&lt;/a&gt;, fixed an &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1132&quot;&gt;infinite recursion in extraction&lt;/a&gt;, and moved the project to &lt;a href=&quot;https://github.com/cppalliance/mrdocs/pull/1077&quot;&gt;use system libs by default&lt;/a&gt;.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;CI infrastructure commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/ed6b3bc&quot;&gt;ed6b3bc&lt;/a&gt; ci: add codecov configuration&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/5426a0a&quot;&gt;5426a0a&lt;/a&gt; ci: use clang for coverage&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/d629173&quot;&gt;d629173&lt;/a&gt; fix(ci): unify redundant LLVM cache keys&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/36a3b51&quot;&gt;36a3b51&lt;/a&gt; ci: update actions to v1.9.1&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/7b2103a&quot;&gt;7b2103a&lt;/a&gt; ci: increase CTest timeout for MSan jobs&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/086becc&quot;&gt;086becc&lt;/a&gt; ci: increase the ctest timeout to 9000&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/adb6821&quot;&gt;adb6821&lt;/a&gt; ci(cpp-matrix): remove the optimized-debug factor&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/9507a38&quot;&gt;9507a38&lt;/a&gt; ci: simplify CI workflow and upgrade cpp-actions to @develop&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/9a5bd3c&quot;&gt;9a5bd3c&lt;/a&gt; ci: skip remote documentation generation on PRs&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/637011f&quot;&gt;637011f&lt;/a&gt; ci: detect and report demo generation failures&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/084322d&quot;&gt;084322d&lt;/a&gt; ci: speed up release demos on PRs&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/471951d&quot;&gt;471951d&lt;/a&gt; ci: skip long tests to speed up CI&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/a5f160b&quot;&gt;a5f160b&lt;/a&gt; ci: increase test coverage for the new XML generator&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/b1fc43c&quot;&gt;b1fc43c&lt;/a&gt; ci: exclude Reflection.hpp from coverage&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/a1f9a82&quot;&gt;a1f9a82&lt;/a&gt; ci: accept any g++-14 version&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/c136a46&quot;&gt;c136a46&lt;/a&gt; ci(website): preserve roadmap directory during deployment&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/4763d86&quot;&gt;4763d86&lt;/a&gt; revert(ci): remove premature roadmap report step&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/3462996&quot;&gt;3462996&lt;/a&gt; ci: revert coverage changes&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/8b2c3e9&quot;&gt;8b2c3e9&lt;/a&gt; ci: align llvm-sanitizer-config with archive basename&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/fdff573&quot;&gt;fdff573&lt;/a&gt; ci: gitignore CI node_modules&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/757d446&quot;&gt;757d446&lt;/a&gt; fix(ci): update the fmt branch reference from master to main&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/a3366b0&quot;&gt;a3366b0&lt;/a&gt; fix(ci): name rolling release packages after the branch&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;test-infrastructure&quot;&gt;Test Infrastructure&lt;/h2&gt;

&lt;p&gt;MrDocs uses &lt;strong&gt;golden tests&lt;/strong&gt;: the expected output for every test case is stored as a file, and the test runner compares the actual output against it. The most important change was adding &lt;strong&gt;multipage golden tests&lt;/strong&gt;. Previously, all golden tests were single-page, but many bugs only manifested in multi-page output (cross-references between pages, navigation links, index generation). We were missing these entirely because we had no way to test them. We also added &lt;strong&gt;output normalization&lt;/strong&gt; (so platform differences do not cause false failures) and &lt;strong&gt;regression categories&lt;/strong&gt; so tests can be grouped and run selectively. A &lt;strong&gt;&lt;code&gt;run_ci_with_act.py&lt;/code&gt;&lt;/strong&gt; script lets contributors run the full CI pipeline locally using &lt;a href=&quot;https://github.com/nektos/act&quot;&gt;act&lt;/a&gt;.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Test infrastructure commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/bf78b1b&quot;&gt;bf78b1b&lt;/a&gt; test: support multipage golden tests&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/d7ad1ce&quot;&gt;d7ad1ce&lt;/a&gt; test: output normalization&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/ccd7f71&quot;&gt;ccd7f71&lt;/a&gt; test: check int tests results in ctest&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/681b0cd&quot;&gt;681b0cd&lt;/a&gt; chore: assign categories to regression tests&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/9146125&quot;&gt;9146125&lt;/a&gt; test: cover additional paths in DocCommentFinalizer.cpp&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/8326417&quot;&gt;8326417&lt;/a&gt; test: run_ci_with_act.py script&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/5527e9c&quot;&gt;5527e9c&lt;/a&gt; test: testClang_stdCxx default is C++26&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/cppalliance/mrdocs/commit/0dfdb02&quot;&gt;0dfdb02&lt;/a&gt; test: –bad is disabled by default&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h1 id=&quot;acknowledgments-and-reflections&quot;&gt;Acknowledgments and Reflections&lt;/h1&gt;

&lt;p&gt;Going into the wild changed MrDocs. The edge cases, the customization requests, and the integration feedback shaped the direction more than any internal roadmap could.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href=&quot;https://github.com/gennaroprota&quot;&gt;Gennaro Prota&lt;/a&gt;&lt;/strong&gt; drove the reflection integration that reduces maintenance burden across the entire codebase. &lt;strong&gt;&lt;a href=&quot;https://github.com/mizvekov&quot;&gt;Matheus Izvekov&lt;/a&gt;&lt;/strong&gt; hardened CI with coverage, sanitizers, and warnings-as-errors, and migrated dependency management to the bootstrap script. &lt;strong&gt;&lt;a href=&quot;https://github.com/julioest&quot;&gt;Julio Estrada&lt;/a&gt;&lt;/strong&gt; and &lt;strong&gt;&lt;a href=&quot;https://github.com/rbbeeston&quot;&gt;Robert Beeston&lt;/a&gt;&lt;/strong&gt; delivered the polished public face of MrDocs. &lt;strong&gt;&lt;a href=&quot;https://github.com/K-ballo&quot;&gt;Agustín Bergé&lt;/a&gt;&lt;/strong&gt; contributed AST and metadata fixes including base member shadowing and alias SFINAE detection. &lt;strong&gt;&lt;a href=&quot;https://github.com/jll63&quot;&gt;Jean-Louis Leroy&lt;/a&gt;&lt;/strong&gt; provided detailed feedback from &lt;a href=&quot;https://github.com/boostorg/openmethod&quot;&gt;Boost.OpenMethod&lt;/a&gt; that drove multiple improvements.&lt;/p&gt;

&lt;p&gt;The most requested feature we have not solved yet is &lt;strong&gt;macro support&lt;/strong&gt; (&lt;a href=&quot;https://github.com/cppalliance/mrdocs/issues/1127&quot;&gt;#1127&lt;/a&gt;). Macros are expanded before parsing and do not appear in the &lt;a href=&quot;https://en.wikipedia.org/wiki/Abstract_syntax_tree&quot;&gt;AST&lt;/a&gt;. Supporting them would require preprocessor-level integration with &lt;a href=&quot;https://clang.llvm.org/&quot;&gt;Clang&lt;/a&gt;. The work ahead also includes &lt;strong&gt;Lua scripting&lt;/strong&gt;, &lt;strong&gt;metadata transforms&lt;/strong&gt;, and &lt;strong&gt;deeper reflection&lt;/strong&gt;, all direct responses to what users told us they need.&lt;/p&gt;

&lt;p&gt;The biggest lesson from this period is that the problems worth solving are the ones users bring. We spent time on an unknowns framework to decide what to explore, but the most impactful work came from people who showed up with a broken demo page, a missing breadcrumb, or a duplicate ellipsis in their generated docs.&lt;/p&gt;

&lt;p&gt;The complete set of changes is available in the &lt;a href=&quot;https://github.com/cppalliance/mrdocs&quot;&gt;MrDocs repository&lt;/a&gt;.&lt;/p&gt;</content><author><name></name></author><category term="alan" /><summary type="html">The questions changed. For a long time, people asked about MrDocs in the abstract: what formats will it support, how will it handle templates, when will it be ready. Then, gradually, the questions became specific. Jean-Louis Leroy, the author of Boost.OpenMethod, became one of our most active sources of feedback. His library exercises corners of C++ that most projects never touch, which means MrDocs gets tested in ways we would not have anticipated. He wanted to know why his template specializations were not sorted correctly. He wanted macro support because Boost libraries rely heavily on macros. He hit a crash when his doc comments contained HTML tables. These are not theoretical questions about a tool that might exist someday. These are questions from someone who already generated documentation with MrDocs and needs it to work better. In our previous post, we described MrDocs transitioning from prototype to product. This post is about what happened when MrDocs went into the wild. Real Projects, Real Problems The Demo Page Breadcrumbs Without a Navigation File Coordinating Two Independent Extensions Edge Cases in the Wild Rendering and Output Under the Hood The MrDocs Website Exploring the Unknowns Reflection: Replacing Boilerplate with Introspection First Steps Toward Extensions Why We Discarded MrDocs-as-Compiler Contributor Experience Automating PR Reviews CI Infrastructure Test Infrastructure Acknowledgments and Reflections Real Projects, Real Problems %%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#e4eee8&quot;, &quot;primaryBorderColor&quot;: &quot;#affbd6&quot;, &quot;primaryTextColor&quot;: &quot;#000000&quot;, &quot;lineColor&quot;: &quot;#baf9d9&quot;, &quot;secondaryColor&quot;: &quot;#f0eae4&quot;, &quot;tertiaryColor&quot;: &quot;#ebeaf4&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%% mindmap root((Feedback)) First impressions Unstyled demos Custom stylesheets Navigation Orphaned pages Breadcrumbs AST edge cases Parameter packs Friend targets Detail namespaces Rendering Description ordering Code blocks Anchor links Runtime JS engine switch Compiler fallback The Demo Page Right after the previous post, where we announced the MVP and encouraged people to try MrDocs, we noticed the demos page was not doing us any favors. Someone shared MrDocs on a developer community and the website started getting traffic. The landing page looked polished, but visitors clicked through to the demos and saw raw, unstyled HTML: no fonts, no spacing, no colors. The HTML generator produced correct semantic markup, and that is technically the point: users are supposed to customize the output with their own stylesheets. But on the demos page, there was no stylesheet at all, and the result looked broken rather than customizable. The custom stylesheet system added five configuration options (stylesheets, linkcss, copycss, no-default-styles, stylesdir) so projects can match their own branding. A bundled default CSS now ships with MrDocs, and it was refined to remove gradients in favor of solid, readable backgrounds. Stylesheet commits 5fe30c1 feat: custom stylesheets 33d985c chore: version is 0.8.0 Breadcrumbs Without a Navigation File MrDocs generates thousands of reference pages, one per C++ symbol. We maintain an Antora extension, the antora-cpp-reference-extension, that integrates these pages into Antora-based documentation sites. But the generated pages end up orphaned from the navigation tree. Users found the navigation confusing: clicking on “boost” in the breadcrumb did not go where expected, and reference pages had no trail showing where they belonged in the hierarchy. The obvious fix would be to list every page in Antora’s nav.adoc, but maintaining a navigation file with thousands of entries that changes every time a symbol is added or removed is not practical. Worse, Antora renders the navigation file in the sidebar, so listing every reference page would flood the UI with thousands of entries. We discussed the problem extensively with the Antora maintainer on the Antora community chat. His position was clear: Antora was designed so that pages must be in the navigation file. Programmatic editing of navigation is not supported. That was not acceptable for us. We needed breadcrumbs that work for thousands of generated pages without polluting the sidebar or requiring a hand-maintained navigation file. The Antora author’s position was reasonable from his perspective (Antora is a general-purpose documentation tool, not a reference generator), but our use case was fundamentally different from what Antora was designed for. The antora-cpp-reference-extension now builds breadcrumbs independently from the navigation file. MrDocs generates reference pages in a directory structure that mirrors the C++ namespace hierarchy (boost/urls/segments_view.adoc lives inside boost/urls/). The extension uses this structure to reconstruct the breadcrumb trail: each directory maps to a namespace, and the page title (which is the symbol name) becomes the last breadcrumb entry. The result reads naturally: Reference &amp;gt; boost &amp;gt; urls &amp;gt; segments_view. Zero changes to the nav file. The sidebar stays clean. Breadcrumbs appear automatically and update when symbols are added or removed. Breadcrumb and reference extension commits antora-cpp-reference-extension ae95eb2 feat: synthesize reference breadcrumbs without nav files 10a4019 feat: add auto base URL detection 6a6c08b docs: auto-base-url option 4f7c79f refactor: enhance release asset validation Coordinating Two Independent Extensions The antora-cpp-reference-extension generates reference pages and breadcrumbs. The antora-cpp-tagfiles-extension resolves cross-library symbol links (so a reference to boost::system::error_code in Boost.URL’s docs links to the correct page in Boost.System’s docs). These are two independent Antora extensions running as separate jobs. The problem was that the reference extension generates tagfiles as a side effect of producing reference pages, and the tagfiles extension needs the most recent version of those tagfiles to resolve links correctly. MrDocs changes the tagfiles every time the corpus changes. Manually keeping them in sync was not sustainable: committing tagfiles to the repository meant they were always stale by the time the next build ran. We made the extensions coordinate directly. The reference extension now hands its tagfile to the tagfiles extension at build time, so the links always reflect the current state of the documentation. The reference extension also gained auto base URL detection, removing the need for manual path configuration when switching between development and production builds. Extension coordination commits antora-cpp-reference-extension 6e8ffcb feat: antora-cpp-tagfiles-extension coordination 8f12576 chore: version is 0.1.0 antora-cpp-tagfiles-extension 98eba40 feat: antora-cpp-reference-extension coordination 5a1723c feat: add global log level control for missing symbols 453f01b chore: version is 0.1.0 Edge Cases in the Wild As more libraries adopted MrDocs, edge cases in C++ symbol extraction surfaced. Boost.Beast exposed a duplicate ellipsis in parameter pack rendering (#1108, #1129): Before: T&amp;amp; emplace(Args...&amp;amp;&amp;amp;... args) After: T&amp;amp; emplace(Args&amp;amp;&amp;amp;... args) Boost.OpenMethod revealed that friend targets were not resolving correctly. Boost.Buffers uncovered a problem with detail namespaces: when a class inherits from a base in a hidden namespace, the inherited members appeared in the documentation but their doc comments were lost (#1107). We fixed this so derived classes inherit documentation from hidden bases. Unnamed structs also sparked an extended design discussion. When C++ code declares constexpr struct {} f{};, MrDocs needs a stable, unique name for hyperlinks. The team established a collaborative design process using shared documents, with Peter Dimov contributing an insight about C compatibility (typedef struct {} T; makes the struct named in C++). AST and metadata commits c85be75 fix: remove duplicate ellipsis in parameter pack expansion c3dbded fix(ast): prevent TU parent from including unmatched globals 76b7b43 fix(ast): canonicalize friend targets 05f5852 fix(metadata): copy impl-defined base docs 35cf1f6 fix: UsingSymbol is SymbolParent c406d57 fix: preserve extraction mode when copying members from derived classes 4e7ef04 fix: prevent infinite recursion when extracting non-regular base class 0a69301 fix: extract and fix some special member function helpers Rendering and Output Users noticed that the manual description of a symbol was buried below long member tables (#1105). On a class with many members, you had to scroll past the entire member listing before finding the author’s explanation of what the class does. We moved the description to appear immediately after the synopsis, matching what cppreference does. Other rendering issues included HTML code blocks not wrapped in &amp;lt;pre&amp;gt; tags, anchor links appearing when the wrapper element was missing, and the Handlebars template engine accumulating special name re-mappings that conflated different symbols. Rendering and output commits d90eae6 fix: hide anchor links when wrapper is not included 92491de fix: manual description comes before member lists 58bf524 fix: remove all special name re-mappings for Handlebars 2a75692 fix: HTML code blocks not wrapped in pre tags 1ebff32 fix: bottomUpTraverse() skips ListBlock items 7b118b1 fix: missing @return command in doc comment Under the Hood We fixed a compiler fallback issue where MrDocs failed when the compilation database referenced a compiler that was not available on the current machine, and corrected sanitizer flag propagation so that UBSan and TSan do not unnecessarily propagate to dependency builds. Build and toolchain commits 235f5c8 fix: fall back to system compilers when database compiler is unavailable f320581 fix: don’t pass sanitizer to dependency builds for UBSan/TSan The MrDocs Website While we were fixing the generated output, Robert Beeston and Julio Estrada were redesigning the MrDocs website. Robert led the design direction, working with a team to develop a visual identity that balances a distinctive retro aesthetic with modern readability, including a dark theme. Julio handled the implementation: mobile-responsive layout, UI styling improvements, cleaner backgrounds and styles, Open Graph and Twitter meta tags for social sharing, and a close button for the docs navigation on smaller screens. For a documentation tool, the website is the first thing potential users see. Having a polished, memorable landing page matters more than it might for other kinds of projects. Exploring the Unknowns The team made a deliberate choice: instead of following a traditional feature roadmap, we would focus on areas of uncertainty (#1113). These were open questions that blocked multiple design decisions at once: MrDocs-as-compiler (#1073): should MrDocs emit “object” files for later “linking,” like a compiler? Scripting extensions (#1128, #881): how should users extend and transform documentation output? Plugins (#58, #1044): how should third-party code register new generators? JSON-only MrDocs: should we add a JSON output format alongside (or replacing) the existing XML structured output? Reflection (#1114): how do we reduce the maintenance burden of the growing metadata model? Cross-linking (#1072): how do we reference symbols in other libraries? The motivation was practical. Each Boost library that adopted MrDocs had its own needs that could not be met by the core tool alone. Boost.URL has implementation_defined namespaces with internal code that should be hidden or transformed in the documentation. Boost.Capy has detail types that should be presented as user-facing types. Coroutines are represented as types in the AST but should be documented as functions. We want MrDocs to be smart enough, with project-specific extensions, that library authors do not have to do workarounds in the source code just to get the documentation right. Rather than hard-coding solutions for each library, the unknowns framework asked: what general mechanisms would let every library solve its own documentation problems? %%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#f7f9ff&quot;, &quot;primaryBorderColor&quot;: &quot;#9aa7e8&quot;, &quot;primaryTextColor&quot;: &quot;#1f2a44&quot;, &quot;lineColor&quot;: &quot;#b4bef2&quot;, &quot;secondaryColor&quot;: &quot;#fbf8ff&quot;, &quot;tertiaryColor&quot;: &quot;#ffffff&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%% mindmap root((Unknowns)) Scripting extensions JS helpers Lua Plugins Generator API DLL loading Reflection Boost.Describe MrDocs.Describe Cross-linking Tagfiles Antora coordination JSON-only MrDocs MrDocs-as-compiler Reflection: Replacing Boilerplate with Introspection MrDocs models many kinds of C++ symbols: functions, classes, namespaces, enums, typedefs, concepts, and more. Each symbol type has metadata, and every piece of code that touches that metadata had to enumerate all fields by hand. Adding a single field to a symbol type meant updating it in: Schema files that describe the metadata format Generators (HTML, AsciiDoc, XML) that produce the output Templates that render individual pages Operators like comparison functions, merge functions (e.g., merging symbols from different translation units when only one is documented), and equality checks Documentation describing the metadata The code itself that populates and transforms the metadata That is roughly ten to fifteen places per field, and missing one caused CI failures that blocked everyone. This was one of the unknowns we identified: how to reduce the maintenance burden as the data model grows. Worse, downstream users who had their own templates and extensions also had to learn about the new fields and update everything accordingly. Gennaro Prota, with his strong background in generic programming and metaprogramming, took ownership of the reflection problem. The work progressed through several stages: Integrate Boost.Describe into the metadata system, replacing hand-written serialization functions Add $meta.type and $meta.bases to all DOM objects so templates can introspect the corpus Replace the XML generator with a reflection-based one (no more hand-maintained XML output) Build a custom reflection system (MrDocs.Describe) tailored to our needs Replace per-type operators with a single generic template The result eliminated the second step entirely: adding a new field to a symbol type no longer requires touching ten other files. The description drives everything, and the serialization, comparison, and merge logic derive from it automatically. Boost.Describe and Boost.Mp11 are private dependencies that do not appear in public headers. Along the way, Gennaro also added function object support, fixed Markdown inline formatting and missing dependent array bounds. Reflection and metadata commits Reflection (Gennaro Prota) d490880 refactor(metadata): integrate Boost.Describe c4dd89a feat: add $meta.type and $meta.bases to all DOM objects d4a64ef fix: replace the XML generator with a reflection-based one 6ce961f refactor: add custom reflection facilities (MrDocs.Describe) eb68494 refactor: migrate all reflection consumers to MrDocs.Describe 8f5391b refactor: replace per-type merge() one-liners with a single generic template e749144 feat: make the reflection consumers public 1ed76ad refactor: replace most per-type tag_invoke overloads with a single generic template 0246935 refactor: replace per-type operator==() and operator&amp;lt;=&amp;gt;() with a single generic template Features and fixes (Gennaro Prota) 93a5032 feat: add function object support f35ebcd fix: rendering of Markdown inline formatting and bullet lists 4ae305b fix: missing dependent array bounds in the output 72fba40 test: add golden tests for a partial class template specialization The reflection work is the foundation for everything that comes next: the extension system, the upcoming Lua scripting, and the metadata transformation pipeline. First Steps Toward Extensions MrDocs supports two extension points: JavaScript for Handlebars template helpers, and Lua for more powerful scripting. The JavaScript engine had been Duktape, but Duktape is no longer actively maintained and only supports ES5.1. We needed a replacement. We evaluated several alternatives (#881): Engine JS Support Windows/MSVC Size License QuickJS ES2023 No (clang-cl only) ~370 KB MIT PrimJS ES2019 No (POSIX only) ~370 KB MIT JerryScript ES5.1 + ES2022 subset Yes ~200 KB Apache 2.0 Escargot ES2025 subset Yes ~400-500 KB LGPL 2.1 MuJS ES5.1 Yes ~200-300 KB ISC Moddable XS ES2025 (~99%) Yes (via SDK) ~100-300 KB Apache/GPL/LGPL mJS Restricted ES6 Yes ~50-60 KB GPL 2.0 / Commercial Elk Minimal ES6 Yes ~20-30 KB GPL 2.0 / Commercial We first experimented with QuickJS, which had the best ES support. But it requires C11 features like &amp;lt;stdatomic.h&amp;gt; and __int128 that plain MSVC does not support. On Windows, users would need Clang with the Visual Studio runtime. PrimJS was POSIX-only. We settled on JerryScript: it supports Windows and MSVC natively, has a small footprint (~200 KB), and covers enough of ES2022 for template helpers. Unlike most alternatives in the table, JerryScript was designed from the ground up to be embedded in other applications, which makes it more like Lua and less like engines that target browsers or standalone runtimes. The JavaScript helpers extension was a single commit but a large one: 85 files changed, 4,287 insertions. The work included: Replacing Duktape with JerryScript across the entire codebase, including build scripts, CMake recipes, and third-party patches Rewriting the C++ JavaScript bindings (JavaScript.hpp and JavaScript.cpp) with shared context lifetime, safer value accessors, and clearer error messages A layered addon system where projects provide JavaScript helpers in a directory structure (generator/common/helpers/ for shared helpers, generator/html/helpers/ for format-specific ones). Multiple addon directories can be layered, so a project’s helpers override or extend the defaults. Golden tests for extension output (js-helper/, js-helper-layering/) to verify that helpers produce the expected documentation 1,335 lines of new JavaScript binding tests covering the engine lifecycle, value conversion, error handling, and helper registration Combined with the public API for registering custom generators, MrDocs now supports customization beyond templates. A library like Boost.Capy could write an extension that transforms its coroutine types into function documentation, without any changes to MrDocs itself. %%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#f7f9ff&quot;, &quot;primaryBorderColor&quot;: &quot;#9aa7e8&quot;, &quot;primaryTextColor&quot;: &quot;#1f2a44&quot;, &quot;lineColor&quot;: &quot;#b4bef2&quot;, &quot;secondaryColor&quot;: &quot;#fbf8ff&quot;, &quot;tertiaryColor&quot;: &quot;#ffffff&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%% flowchart LR A[Clang AST] --&amp;gt; B[Extraction] B --&amp;gt; C[Corpus] C --&amp;gt; D[Transformation Extensions] D --&amp;gt; E[Handlebars Generators] E --&amp;gt; F[Documentation Templates] F --&amp;gt; H[HTML / AsciiDoc] F --&amp;gt; G[Template Extensions] G --&amp;gt; F D -.-&amp;gt; I[XML] The vision for extensions has two layers: Transformation extensions operate on the corpus between extraction and generation. A library could transform its internal types into the documentation structure it wants. This layer is not yet implemented. Template extensions (JavaScript helpers) operate inside the Handlebars templates that produce HTML and AsciiDoc output. This is the layer we shipped. Lua scripts for more powerful scripting in both layers Extension and generator commits 0f3ecb4 feat: javascript helpers extension (85 files, 4,287 insertions) 930a5ea fix: jerry_port_context_free wrong signature causes silent corruption 8da0930 feat(lib): public API for generator registration 788c1ba feat(generators): tables for symbols have headers Why We Discarded MrDocs-as-Compiler One unknown we explored and deliberately discarded was MrDocs-as-compiler (#1073). The idea, proposed by Peter Dimov, was to treat MrDocs like a compiler: emit “object” files per translation unit, then “link” them to produce the final reference. CMake would invoke MrDocs as if it were Clang, with identical command-line options. We spent time studying tools that work this way: clang-tidy, clang-doc, include-what-you-use. What we found is that tricking CMake into thinking MrDocs is a real compiler is not trivial. Every tool that tries this approach ends up needing either a coordinator binary (reimplementing what MrDocs already has) or CMake helper scripts. Both add workflows rather than simplifying them. The experience from the Boost ecosystem reinforced this: no Boost project uses any of these compiler-like tools for static analysis, and the reason is complexity. People who find the compilation database workflow too involved are going to be even less inclined to adopt a tool that requires them to pretend to be a compiler. We decided to keep MrDocs as a single-step tool that reads a compilation database and produces output, rather than splitting it into a multi-binary pipeline that would need its own coordination layer. Contributor Experience As more people contributed to MrDocs, the gap between “clone the repo” and “submit a useful PR” needed closing. The biggest change was the bootstrap script, which reduced the entire build setup to a single python bootstrap.py command (covered in a separate post). Beyond the bootstrap, we split the contributor guide into focused sections, added reference documentation for MrDocs comment syntax (so contributors know what @copydoc, @see, and other commands do), and created a run_all_tests script that runs the full test suite locally without needing to understand the CMake test configuration. Onboarding commits b103cba docs(reference): mrdocs comments 9b7ec24 feat(util): run_all_tests script 5902699 docs: update packages 302f0a6 docs: split contribute.adoc guide Automating PR Reviews MrDocs PRs tend to be large and hard to review. A single PR might touch the AST visitor, the Handlebars templates, the Antora extension, the CI configuration, and hundreds of golden test files (when an intentional change to the output format updates the expected output for every test case). We found ourselves making the same review comments over and over. We set up Danger.js to catch these patterns before human reviewers see the PR. The most important check is detecting when source code changes do not include corresponding tests: if someone changes extraction logic but does not update the golden tests, or changes a template without updating the expected output, Danger flags it. Beyond that: Categorizes all file changes into scopes (source, tests, golden-tests, docs, CI, build, tooling) and generates a summary table showing churn per scope Validates commit messages against Conventional Commits format Warns when a single commit exceeds 2,000 lines of source churn (encouraging smaller, reviewable slices) Flags mismatched commit types (e.g., a feat: commit that only touches test files suggests test: instead) Rejects PR descriptions under 40 characters Ignores the test check for refactor-only PRs where the tests are expected to remain unchanged Even when there are no warnings, the scope summary table gives reviewers an immediate sense of what a large PR touches. On a PR that changes 500 lines of source and 3,000 lines of golden tests, the table makes it clear that the bulk of the diff is expected test output, not new logic. Danger.js commits 6f5f6e9 ci: setup danger.js 5429b2e ci(danger): align report table and add top-files summary 240921d ci(danger): split PR target ci workflows 08c46b6 ci(danger): correct file delta calculation in reports 2cfd081 ci(danger): adjust large commit threshold 71845c8 ci(danger): map root files into explicit scopes 17b0a57 ci(danger): ignore test check for refactor-only PRs 6481fd3 ci(danger): simplify CI naming fd7d248 ci(danger): omit empty sections from report 7502961 ci(danger): categorize util/bootstrap as build scope 57e191e ci(danger): better markdown format CI Infrastructure We integrated Codecov for tracking test coverage across PRs and switched from GCC to Clang for coverage (more accurate AST-based measurement). CI speed was a recurring concern: we skipped remote documentation generation on PRs, sped up release demos, and skipped long tests that were not catching new bugs. LLVM cache keys were unified to avoid redundant builds, and CTest timeouts were increased for sanitizer jobs that run significantly slower. Matheus Izvekov contributed the Clang coverage switch, fixed an infinite recursion in extraction, and moved the project to use system libs by default. CI infrastructure commits ed6b3bc ci: add codecov configuration 5426a0a ci: use clang for coverage d629173 fix(ci): unify redundant LLVM cache keys 36a3b51 ci: update actions to v1.9.1 7b2103a ci: increase CTest timeout for MSan jobs 086becc ci: increase the ctest timeout to 9000 adb6821 ci(cpp-matrix): remove the optimized-debug factor 9507a38 ci: simplify CI workflow and upgrade cpp-actions to @develop 9a5bd3c ci: skip remote documentation generation on PRs 637011f ci: detect and report demo generation failures 084322d ci: speed up release demos on PRs 471951d ci: skip long tests to speed up CI a5f160b ci: increase test coverage for the new XML generator b1fc43c ci: exclude Reflection.hpp from coverage a1f9a82 ci: accept any g++-14 version c136a46 ci(website): preserve roadmap directory during deployment 4763d86 revert(ci): remove premature roadmap report step 3462996 ci: revert coverage changes 8b2c3e9 ci: align llvm-sanitizer-config with archive basename fdff573 ci: gitignore CI node_modules 757d446 fix(ci): update the fmt branch reference from master to main a3366b0 fix(ci): name rolling release packages after the branch Test Infrastructure MrDocs uses golden tests: the expected output for every test case is stored as a file, and the test runner compares the actual output against it. The most important change was adding multipage golden tests. Previously, all golden tests were single-page, but many bugs only manifested in multi-page output (cross-references between pages, navigation links, index generation). We were missing these entirely because we had no way to test them. We also added output normalization (so platform differences do not cause false failures) and regression categories so tests can be grouped and run selectively. A run_ci_with_act.py script lets contributors run the full CI pipeline locally using act. Test infrastructure commits bf78b1b test: support multipage golden tests d7ad1ce test: output normalization ccd7f71 test: check int tests results in ctest 681b0cd chore: assign categories to regression tests 9146125 test: cover additional paths in DocCommentFinalizer.cpp 8326417 test: run_ci_with_act.py script 5527e9c test: testClang_stdCxx default is C++26 0dfdb02 test: –bad is disabled by default Acknowledgments and Reflections Going into the wild changed MrDocs. The edge cases, the customization requests, and the integration feedback shaped the direction more than any internal roadmap could. Gennaro Prota drove the reflection integration that reduces maintenance burden across the entire codebase. Matheus Izvekov hardened CI with coverage, sanitizers, and warnings-as-errors, and migrated dependency management to the bootstrap script. Julio Estrada and Robert Beeston delivered the polished public face of MrDocs. Agustín Bergé contributed AST and metadata fixes including base member shadowing and alias SFINAE detection. Jean-Louis Leroy provided detailed feedback from Boost.OpenMethod that drove multiple improvements. The most requested feature we have not solved yet is macro support (#1127). Macros are expanded before parsing and do not appear in the AST. Supporting them would require preprocessor-level integration with Clang. The work ahead also includes Lua scripting, metadata transforms, and deeper reflection, all direct responses to what users told us they need. The biggest lesson from this period is that the problems worth solving are the ones users bring. We spent time on an unknowns framework to decide what to explore, but the most impactful work came from people who showed up with a broken demo page, a missing breadcrumb, or a duplicate ellipsis in their generated docs. The complete set of changes is available in the MrDocs repository.</summary></entry><entry><title type="html">Boost.URL: Audited, Constexpr, and Polished</title><link href="http://cppalliance.org/alan/2026/04/21/Alan.html" rel="alternate" type="text/html" title="Boost.URL: Audited, Constexpr, and Polished" /><published>2026-04-21T00:00:00+00:00</published><updated>2026-04-21T00:00:00+00:00</updated><id>http://cppalliance.org/alan/2026/04/21/Alan</id><content type="html" xml:base="http://cppalliance.org/alan/2026/04/21/Alan.html">&lt;p&gt;We had been putting off the &lt;a href=&quot;https://github.com/boostorg/url&quot;&gt;Boost.URL&lt;/a&gt; security review for a while. There was always something more urgent. When the review finally happened, it confirmed what we hoped: the core parsing logic held up well. Around the same time, a constexpr feature request that we had been dismissing suddenly became a cross-library collaboration when other Boost maintainers started applying changes to their own libraries. And while working on &lt;a href=&quot;https://github.com/cppalliance/beast2&quot;&gt;Boost.Beast2&lt;/a&gt; integration, we noticed friction in common URL operations that led us to clear a backlog of usability improvements.&lt;/p&gt;

&lt;!-- prettier-ignore --&gt;

&lt;ul id=&quot;markdown-toc&quot;&gt;

&lt;li&gt;&lt;a href=&quot;#security-review&quot; id=&quot;markdown-toc-security-review&quot;&gt;Security Review&lt;/a&gt; &lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;#round-1-1207-findings-february-2-2026&quot; id=&quot;markdown-toc-round-1-1207-findings-february-2-2026&quot;&gt;Round 1: 1,207 Findings (February 2, 2026)&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#round-2-27-findings-february-17-2026&quot; id=&quot;markdown-toc-round-2-27-findings-february-17-2026&quot;&gt;Round 2: 27 Findings (February 17, 2026)&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#round-3-15-findings-april-2-2026&quot; id=&quot;markdown-toc-round-3-15-findings-april-2-2026&quot;&gt;Round 3: 15 Findings (April 2, 2026)&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#compile-time-url-parsing&quot; id=&quot;markdown-toc-compile-time-url-parsing&quot;&gt;Compile-Time URL Parsing&lt;/a&gt; &lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;#the-conversation-that-changed-everything&quot; id=&quot;markdown-toc-the-conversation-that-changed-everything&quot;&gt;The Conversation That Changed Everything&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#error-handling-at-compile-time&quot; id=&quot;markdown-toc-error-handling-at-compile-time&quot;&gt;Error Handling at Compile Time&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#the--wmaybe-uninitialized-problem&quot; id=&quot;markdown-toc-the--wmaybe-uninitialized-problem&quot;&gt;The &lt;code&gt;-Wmaybe-uninitialized&lt;/code&gt; Problem&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#the-shared-library-problem&quot; id=&quot;markdown-toc-the-shared-library-problem&quot;&gt;The Shared Library Problem&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#the-result&quot; id=&quot;markdown-toc-the-result&quot;&gt;The Result&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#usability-improvements&quot; id=&quot;markdown-toc-usability-improvements&quot;&gt;Usability Improvements&lt;/a&gt; &lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;#convenience-functions&quot; id=&quot;markdown-toc-convenience-functions&quot;&gt;Convenience Functions&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#c20-integration&quot; id=&quot;markdown-toc-c20-integration&quot;&gt;C++20 Integration&lt;/a&gt;&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#performance&quot; id=&quot;markdown-toc-performance&quot;&gt;Performance&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;#acknowledgments-and-reflections&quot; id=&quot;markdown-toc-acknowledgments-and-reflections&quot;&gt;Acknowledgments and Reflections&lt;/a&gt;&lt;/li&gt;

&lt;/ul&gt;

&lt;h1 id=&quot;security-review&quot;&gt;Security Review&lt;/h1&gt;

&lt;p&gt;The &lt;a href=&quot;https://cppalliance.org/&quot;&gt;C++ Alliance&lt;/a&gt; arranges professional security audits for the libraries we maintain. The results for &lt;a href=&quot;https://www.boost.org/doc/libs/release/libs/beast/doc/html/beast/quick_start/security_review_bishop_fox.html&quot;&gt;Boost.Beast (2020)&lt;/a&gt; and &lt;a href=&quot;https://cppalliance.org/pdf/C%20Plus%20Plus%20Alliance%20-%20Boost%20JSON%20Security%20Assessment%202020%20-%20Assessment%20Report%20-%2020210317.pdf&quot;&gt;Boost.JSON (2021)&lt;/a&gt; are publicly available. For Boost.URL, we always had the plan but kept delaying because there was so much other work to do first. That delay turned out to be a good thing: we found and fixed issues ourselves first, so the reviewers could focus on the subtle problems.&lt;/p&gt;

&lt;p&gt;&lt;a href=&quot;https://www.laurellye.com/&quot;&gt;Laurel Lye Systems Engineering&lt;/a&gt; conducted &lt;strong&gt;three rounds&lt;/strong&gt; of assessment. Each finding was manually reviewed against the source code and categorized as a confirmed bug (fixed), a false positive, or a deliberate design choice. For every confirmed bug, we also proposed new test cases to prevent regressions.&lt;/p&gt;

&lt;h2 id=&quot;round-1-1207-findings-february-2-2026&quot;&gt;Round 1: 1,207 Findings (February 2, 2026)&lt;/h2&gt;

&lt;p&gt;The first assessment was the broadest. Of 1,207 findings, &lt;strong&gt;15 were confirmed bugs&lt;/strong&gt; resulting in fix commits. The vast majority were false positives or by-design patterns:&lt;/p&gt;

&lt;table&gt;

&lt;thead&gt;

&lt;tr&gt;

&lt;th&gt;Verdict&lt;/th&gt;

&lt;th&gt;CRITICAL&lt;/th&gt;

&lt;th&gt;HIGH&lt;/th&gt;

&lt;th&gt;MEDIUM&lt;/th&gt;

&lt;th&gt;LOW&lt;/th&gt;

&lt;th&gt;INFO&lt;/th&gt;

&lt;th&gt;Total&lt;/th&gt;

&lt;/tr&gt;

&lt;/thead&gt;

&lt;tbody&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;FIXED&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;9&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;2&lt;/td&gt;

&lt;td&gt;3&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;15&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;FALSE POSITIVE&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;3&lt;/td&gt;

&lt;td&gt;47&lt;/td&gt;

&lt;td&gt;46&lt;/td&gt;

&lt;td&gt;186&lt;/td&gt;

&lt;td&gt;110&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;392&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;BY DESIGN&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;129&lt;/td&gt;

&lt;td&gt;445&lt;/td&gt;

&lt;td&gt;170&lt;/td&gt;

&lt;td&gt;56&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;800&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;Total&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;4&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;185&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;491&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;358&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;169&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;1,207&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;/tbody&gt;

&lt;/table&gt;

&lt;p&gt;The single &lt;strong&gt;CRITICAL&lt;/strong&gt; fix was a loop condition in &lt;code&gt;url_base&lt;/code&gt; that dereferenced &lt;code&gt;*it&lt;/code&gt; before checking &lt;code&gt;it != end&lt;/code&gt;. Three other CRITICAL findings were false positives: the audit flagged raw-pointer writes in the format engine, but these use a two-phase measure/format design that guarantees the buffer is pre-sized correctly.&lt;/p&gt;

&lt;p&gt;Most false positives fell into recognizable themes:&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;strong&gt;&lt;code&gt;BOOST_ASSERT&lt;/code&gt; as sole bounds check&lt;/strong&gt; (29 HIGH findings): internal &lt;code&gt;_unsafe&lt;/code&gt; functions rely on preconditions validated by the public API. The &lt;code&gt;_unsafe&lt;/code&gt; suffix signals the contract. This is the standard Boost/STL pattern (&lt;code&gt;std::vector::operator[]&lt;/code&gt; vs &lt;code&gt;at()&lt;/code&gt;).&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Non-owning view lifetime safety&lt;/strong&gt; (27 HIGH findings): &lt;code&gt;string_view&lt;/code&gt; and &lt;code&gt;url_view&lt;/code&gt; types do not own their data. The audit flagged potential use-after-free, but lifetime management is the caller’s responsibility by design.&lt;/li&gt;

&lt;li&gt;&lt;strong&gt;Atomic reference counting&lt;/strong&gt; (multiple findings across all rounds): the audit tool did not recognize the &lt;code&gt;#ifdef BOOST_URL_DISABLE_THREADS&lt;/code&gt; guard that switches between &lt;code&gt;std::atomic&amp;lt;std::size_t&amp;gt;&lt;/code&gt; and plain &lt;code&gt;std::size_t&lt;/code&gt;.&lt;/li&gt;

&lt;/ul&gt;

&lt;details&gt;

&lt;summary&gt;Round 1 fix commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/bcdc891&quot;&gt;bcdc891&lt;/a&gt; CRITICAL: url_base loop condition order&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/ec15fce&quot;&gt;ec15fce&lt;/a&gt; HIGH: encode() UB pointer arithmetic for small buffers&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/81fcb95&quot;&gt;81fcb95&lt;/a&gt; HIGH: LLONG_MIN negation UB in format&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/42c8fe7&quot;&gt;42c8fe7&lt;/a&gt; HIGH: ci_less::operator() return type&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/76279f5&quot;&gt;76279f5&lt;/a&gt; HIGH: incorrect noexcept in segments_base::front() and back()&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/d4ae92d&quot;&gt;d4ae92d&lt;/a&gt; HIGH: recycled_ptr::get() nullptr when empty&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/8d98fe6&quot;&gt;8d98fe6&lt;/a&gt; LOW: decode() noexcept on throwing template&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;p&gt;The proportion of false positives to confirmed bugs was large enough that we discussed a second round with Laurel Lye, where we shared the false positive categories we had identified so they could be more targeted.&lt;/p&gt;

&lt;h2 id=&quot;round-2-27-findings-february-17-2026&quot;&gt;Round 2: 27 Findings (February 17, 2026)&lt;/h2&gt;

&lt;p&gt;The second assessment was more targeted. The reviewers had learned from our Round 1 triage and produced fewer false positives:&lt;/p&gt;

&lt;table&gt;

&lt;thead&gt;

&lt;tr&gt;

&lt;th&gt;Verdict&lt;/th&gt;

&lt;th&gt;HIGH&lt;/th&gt;

&lt;th&gt;MEDIUM&lt;/th&gt;

&lt;th&gt;LOW&lt;/th&gt;

&lt;th&gt;INFO&lt;/th&gt;

&lt;th&gt;Total&lt;/th&gt;

&lt;/tr&gt;

&lt;/thead&gt;

&lt;tbody&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;FIXED&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;7&lt;/td&gt;

&lt;td&gt;3&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;12&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;FALSE POSITIVE&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;2&lt;/td&gt;

&lt;td&gt;2&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;4&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;BY DESIGN&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;2&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;ALREADY FIXED&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;5&lt;/td&gt;

&lt;td&gt;4&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;9&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;Total&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;9&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;10&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;6&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;2&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;27&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;/tbody&gt;

&lt;/table&gt;

&lt;p&gt;9 of the 27 findings had &lt;strong&gt;already been fixed&lt;/strong&gt; in Round 1 commits. The new confirmed bugs included a heap overflow in format center-alignment padding (&lt;code&gt;lpad = w / 2&lt;/code&gt; used total width instead of padding amount), an infinite loop in &lt;code&gt;decode_view::ends_with&lt;/code&gt; with empty strings, and an OOB read in &lt;code&gt;ci_is_less&lt;/code&gt; on mismatched-length strings.&lt;/p&gt;

&lt;p&gt;Both rounds are tracked in &lt;a href=&quot;https://github.com/boostorg/url/pull/982&quot;&gt;PR #982&lt;/a&gt;.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Round 2 fix commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/d06df88&quot;&gt;d06df88&lt;/a&gt; HIGH: format center-alignment padding&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/4fe2438&quot;&gt;4fe2438&lt;/a&gt; HIGH: decode_view::ends_with with empty string&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/f5727ed&quot;&gt;f5727ed&lt;/a&gt; HIGH: stale pattern n.path after colon-encoding&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/d045d71&quot;&gt;d045d71&lt;/a&gt; HIGH: ci_is_less OOB read&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/88efbae&quot;&gt;88efbae&lt;/a&gt; HIGH: recycled_ptr copy self-assignment&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/fe4bdf6&quot;&gt;fe4bdf6&lt;/a&gt; MEDIUM: url move self-assignment&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/ab5d812&quot;&gt;ab5d812&lt;/a&gt; MEDIUM: encode_one signed char right-shift&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/b662a8f&quot;&gt;b662a8f&lt;/a&gt; MEDIUM: encode() noexcept on throwing template&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/5bc52ed&quot;&gt;5bc52ed&lt;/a&gt; LOW: port_rule has_number for port zero at end of input&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/9c9850f&quot;&gt;9c9850f&lt;/a&gt; INFO: ci_equal arguments by const reference&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/4f466ce&quot;&gt;4f466ce&lt;/a&gt; test: public interface boundary and fuzz tests&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;h2 id=&quot;round-3-15-findings-april-2-2026&quot;&gt;Round 3: 15 Findings (April 2, 2026)&lt;/h2&gt;

&lt;p&gt;The third round was the shortest and the most precise. Of 15 findings, &lt;strong&gt;4 were confirmed bugs&lt;/strong&gt; and &lt;strong&gt;11 were false positives&lt;/strong&gt;. No CRITICAL findings. The false positives were the same recurring themes (atomic refcounting, pre-validated format strings, preconditions guaranteed by callers).&lt;/p&gt;

&lt;table&gt;

&lt;thead&gt;

&lt;tr&gt;

&lt;th&gt;Verdict&lt;/th&gt;

&lt;th&gt;HIGH&lt;/th&gt;

&lt;th&gt;MEDIUM&lt;/th&gt;

&lt;th&gt;LOW&lt;/th&gt;

&lt;th&gt;Total&lt;/th&gt;

&lt;/tr&gt;

&lt;/thead&gt;

&lt;tbody&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;FIXED&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;0&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;3&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;4&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;FALSE POSITIVE&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;4&lt;/td&gt;

&lt;td&gt;6&lt;/td&gt;

&lt;td&gt;1&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;11&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;Total&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;4&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;7&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;4&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;&lt;strong&gt;15&lt;/strong&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;/tbody&gt;

&lt;/table&gt;

&lt;p&gt;The confirmed bugs were more subtle: a decoded-length calculation error in &lt;code&gt;segments_iter_impl::decrement()&lt;/code&gt; that only manifested during backward iteration over percent-encoded paths, two &lt;a href=&quot;https://en.cppreference.com/w/cpp/language/noexcept_spec&quot;&gt;&lt;code&gt;noexcept&lt;/code&gt;&lt;/a&gt; specifications on functions that allocate &lt;code&gt;std::string&lt;/code&gt; (which can throw &lt;code&gt;bad_alloc&lt;/code&gt;), and a &lt;code&gt;memcpy&lt;/code&gt; with null source when size is zero (undefined behavior per the C standard, even though it copies nothing).&lt;/p&gt;

&lt;p&gt;This round is tracked in &lt;a href=&quot;https://github.com/boostorg/url/pull/988&quot;&gt;PR #988&lt;/a&gt;.&lt;/p&gt;

&lt;details&gt;

&lt;summary&gt;Round 3 fix commits&lt;/summary&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/3ca2d71&quot;&gt;3ca2d71&lt;/a&gt; MEDIUM: segments_iter_impl decoded-length in decrement()&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/b1f6f8e&quot;&gt;b1f6f8e&lt;/a&gt; LOW: param noexcept on throwing constructor&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/d42c748&quot;&gt;d42c748&lt;/a&gt; LOW: string_view_base noexcept on throwing operator std::string()&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/f963383&quot;&gt;f963383&lt;/a&gt; LOW: url_view memcpy with null source when size is zero&lt;/li&gt;

&lt;/ul&gt;

&lt;/details&gt;

&lt;p&gt;The progression from 1,207 findings to 27 to 15 shows the reviewers learning the peculiarities of our codebase. The ratio of false positives dropped with each round, and the confirmed bugs got more subtle.&lt;/p&gt;

&lt;div class=&quot;mermaid&quot;&gt;

%%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#e4eee8&quot;, &quot;primaryBorderColor&quot;: &quot;#affbd6&quot;, &quot;primaryTextColor&quot;: &quot;#000000&quot;, &quot;lineColor&quot;: &quot;#baf9d9&quot;, &quot;secondaryColor&quot;: &quot;#f0eae4&quot;, &quot;tertiaryColor&quot;: &quot;#ebeaf4&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%%

mindmap

root((Confirmed Bugs))

UB in edge cases

encode_one right-shift

LLONG_MIN negation

pointer arithmetic

Self-assignment

url move

recycled_ptr copy

OOB reads

ci_is_less

decode_view ends_with

Incorrect noexcept

encode / decode

segments_base front/back

param constructor

string_view_base operator

Iterator bugs

segments decoded-length

Null pointer

recycled_ptr get

url_view memcpy

&lt;/div&gt;

&lt;h1 id=&quot;compile-time-url-parsing&quot;&gt;Compile-Time URL Parsing&lt;/h1&gt;

&lt;p&gt;&lt;a href=&quot;https://github.com/boostorg/url/issues/890&quot;&gt;&lt;code&gt;constexpr&lt;/code&gt; URL parsing&lt;/a&gt; has been one of the most recurring requests since the library’s inception. Every few months someone would ask about it, and every few months we would decide the refactoring cost was too high. The parsing engine is heavily buffer-oriented, and moving enough code into headers for &lt;a href=&quot;https://en.cppreference.com/w/cpp/language/constexpr&quot;&gt;&lt;code&gt;constexpr&lt;/code&gt;&lt;/a&gt; evaluation required careful refactoring without breaking the shared library build.&lt;/p&gt;

&lt;p&gt;When we finally prototyped it, the diff touched thousands of lines, but most of those were &lt;strong&gt;code being moved from source files to headers&lt;/strong&gt; rather than new logic. The actual new code was limited to alternative code paths to bypass non-literal types and refactoring &lt;code&gt;url_view_base&lt;/code&gt; to eliminate a self-referencing pointer that prevented &lt;code&gt;constexpr&lt;/code&gt; evaluation. Still, given the size of the change, we initially marked it as unactionable and moved on to the security review.&lt;/p&gt;

&lt;p&gt;Beyond the refactoring cost, we had &lt;strong&gt;blockers beyond our control&lt;/strong&gt;. Our parsing code depended on &lt;a href=&quot;https://github.com/boostorg/optional/issues/143&quot;&gt;&lt;code&gt;boost::optional&lt;/code&gt;&lt;/a&gt; (not a literal type, no constexpr constructors), &lt;a href=&quot;https://github.com/boostorg/variant2&quot;&gt;&lt;code&gt;boost::variant2&lt;/code&gt;&lt;/a&gt; (not literal when containing &lt;code&gt;optional&lt;/code&gt;), and &lt;a href=&quot;https://github.com/boostorg/system/issues/141&quot;&gt;&lt;code&gt;boost::system::result&lt;/code&gt;&lt;/a&gt; (could not be constructed with a custom &lt;code&gt;error_code&lt;/code&gt; in constexpr because &lt;a href=&quot;https://www.boost.org/doc/libs/release/libs/system/doc/html/system.html#ref_error_category&quot;&gt;&lt;code&gt;error_category::failed()&lt;/code&gt;&lt;/a&gt; is virtual). Without changes to those libraries, constexpr URL parsing was not possible regardless of how much we refactored our own code.&lt;/p&gt;

&lt;h2 id=&quot;the-conversation-that-changed-everything&quot;&gt;The Conversation That Changed Everything&lt;/h2&gt;

&lt;p&gt;Then &lt;a href=&quot;https://github.com/pdimov&quot;&gt;Peter Dimov&lt;/a&gt;, the maintainer of &lt;a href=&quot;https://github.com/boostorg/system&quot;&gt;Boost.System&lt;/a&gt; and &lt;a href=&quot;https://github.com/boostorg/variant2&quot;&gt;Boost.Variant2&lt;/a&gt;, joined the &lt;a href=&quot;https://github.com/boostorg/url/issues/890&quot;&gt;conversation&lt;/a&gt;. We had assumed that &lt;code&gt;system::result&amp;lt;T&amp;gt;&lt;/code&gt; could not be &lt;code&gt;constexpr&lt;/code&gt; in C++14 because it wraps &lt;code&gt;error_code&lt;/code&gt;, which uses virtual functions. Peter &lt;a href=&quot;https://github.com/boostorg/url/issues/890#issuecomment-2720949684&quot;&gt;pointed out&lt;/a&gt; that &lt;strong&gt;&lt;code&gt;system::result&amp;lt;T&amp;gt;&lt;/code&gt; is already a literal type&lt;/strong&gt; in C++14 when &lt;code&gt;T&lt;/code&gt; is literal and the error code is not custom. Boost.URL uses a &lt;strong&gt;custom error code category&lt;/strong&gt;, and constructing a &lt;code&gt;result&lt;/code&gt; from a custom &lt;code&gt;error_code&lt;/code&gt; requires calling &lt;code&gt;error_category::failed()&lt;/code&gt;, which is virtual and therefore not &lt;code&gt;constexpr&lt;/code&gt; before C++20. Peter &lt;a href=&quot;https://github.com/boostorg/url/issues/890#issuecomment-3869061934&quot;&gt;offered to fix this&lt;/a&gt; in Boost.System (&lt;a href=&quot;https://github.com/boostorg/system/issues/141&quot;&gt;#141&lt;/a&gt;, &lt;a href=&quot;https://github.com/boostorg/system/commit/af53f17&quot;&gt;af53f17&lt;/a&gt;) for C++20 so that custom error codes would also work at compile time.&lt;/p&gt;

&lt;div class=&quot;admonition&quot;&gt;&lt;div class=&quot;admonition-title&quot;&gt;Allowing constexpr virtual functions in C++20&lt;/div&gt;

&lt;p&gt;Peter Dimov is also one of the authors of &lt;a href=&quot;https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1064r0.html&quot;&gt;P1064: “Allowing Virtual Function Calls in Constant Expressions”&lt;/a&gt;, the C++ committee proposal that made &lt;code&gt;constexpr&lt;/code&gt; virtual functions possible in C++20. The paper uses &lt;code&gt;error_code&lt;/code&gt; and &lt;code&gt;error_category&lt;/code&gt; as the motivating example.&lt;/p&gt;

&lt;/div&gt;

&lt;p&gt;That &lt;strong&gt;shifted the problem&lt;/strong&gt;. Instead of building our own &lt;code&gt;constexpr_result&amp;lt;T&amp;gt;&lt;/code&gt; type to bypass the entire error handling system, we could use &lt;code&gt;system::result&lt;/code&gt; directly in C++20. The scope of the refactoring shrank, and we focused on &lt;strong&gt;C++20 as the initial target&lt;/strong&gt;. The remaining blocker was that &lt;code&gt;system::result&amp;lt;T&amp;gt;&lt;/code&gt; requires &lt;code&gt;T&lt;/code&gt; to be a literal type, and we use &lt;code&gt;boost::optional&lt;/code&gt; heavily in our parsing code. &lt;strong&gt;&lt;code&gt;boost::optional&lt;/code&gt; was not a literal type.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href=&quot;https://github.com/akrzemi1&quot;&gt;Andrzej Krzemieński&lt;/a&gt;, the Boost.Optional maintainer, &lt;a href=&quot;https://github.com/boostorg/optional/issues/143&quot;&gt;started working on it&lt;/a&gt;. The conversation went back and forth on the &lt;strong&gt;C++14 constraints&lt;/strong&gt;: &lt;code&gt;std::addressof&lt;/code&gt; is not &lt;code&gt;constexpr&lt;/code&gt; until C++17, mandatory copy elision is only available in C++17, and there were questions about what subset of constructors could realistically become &lt;code&gt;constexpr&lt;/code&gt; in C++14. After several iterations (including a &lt;code&gt;feature/constexpr&lt;/code&gt; branch), the &lt;a href=&quot;https://github.com/boostorg/optional/commit/3df2337&quot;&gt;&lt;strong&gt;constexpr implementation&lt;/strong&gt; landed on &lt;code&gt;develop&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;With &lt;strong&gt;&lt;code&gt;optional&lt;/code&gt; becoming literal&lt;/strong&gt;, &lt;code&gt;boost::variant2&lt;/code&gt; containing &lt;code&gt;optional&lt;/code&gt; could also become literal. All three blockers were now resolved. Peter had fixed Boost.System, Andrzej had fixed Boost.Optional, and we contributed fixes to Boost.Variant2. &lt;strong&gt;There was no going back&lt;/strong&gt;: we could no longer dismiss the constexpr feature after three library maintainers had already done their part.&lt;/p&gt;

&lt;div class=&quot;mermaid&quot;&gt;

%%{init: {&quot;theme&quot;: &quot;base&quot;, &quot;themeVariables&quot;: {&quot;primaryColor&quot;: &quot;#f7f9ff&quot;, &quot;primaryBorderColor&quot;: &quot;#9aa7e8&quot;, &quot;primaryTextColor&quot;: &quot;#1f2a44&quot;, &quot;lineColor&quot;: &quot;#b4bef2&quot;, &quot;secondaryColor&quot;: &quot;#fbf8ff&quot;, &quot;tertiaryColor&quot;: &quot;#ffffff&quot;, &quot;fontSize&quot;: &quot;14px&quot;}}}%%

flowchart TD

A[Boost.URL constexpr parsing] --&amp;gt; B[Boost.Optional]

A --&amp;gt; C[Boost.Variant2]

A --&amp;gt; D[Boost.System]

B --&amp;gt; E[boost::optional constexpr]

C --&amp;gt; F[boost::variant2::variant constexpr]

D --&amp;gt; G[boost::system::result constexpr]

D --&amp;gt; H[boost::system::error_code constexpr]

&lt;/div&gt;

&lt;details&gt;

&lt;summary&gt;Cross-library commits for constexpr support&lt;/summary&gt;

&lt;p&gt;&lt;strong&gt;Boost.URL&lt;/strong&gt; (&lt;a href=&quot;https://github.com/boostorg/url/pull/976&quot;&gt;PR #976&lt;/a&gt;, &lt;a href=&quot;https://github.com/boostorg/url/pull/981&quot;&gt;PR #981&lt;/a&gt;)&lt;/p&gt;

&lt;ul&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/0a2c39f&quot;&gt;0a2c39f&lt;/a&gt; feat: constexpr URL parsing for C++20&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/b9db439&quot;&gt;b9db439&lt;/a&gt; build: remove -Wno-maybe-uninitialized from GCC flags (see &lt;a href=&quot;#the--wmaybe-uninitialized-problem&quot;&gt;below&lt;/a&gt;)&lt;/li&gt;

&lt;li&gt;&lt;a href=&quot;https://github.com/boostorg/url/commit/59b4540&quot;&gt;59b4540&lt;/a&gt; fix: suppress GCC false-positive -Wmaybe-uninitialized in tuple_rule (see &lt;a href=&quot;#the--wmaybe-uninitialized-problem&quot;&gt;below&lt;/a&gt;)&lt;/li&gt;

&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Boost.Optional&lt;/strong&gt; (&lt;a href=&quot;https://github.com/boostorg/optional/issues/143&quot;&gt;issue #143&lt;/a&gt;, &lt;a href=&quot;https://github.com/boostorg/optional/pull/145&quot;&gt;PR #145&lt;/a&gt;)&lt;/p&gt;

&lt;ul&gt;