fix: rendering of Markdown inline formatting and bullet lists (#1156)

[gennaroprota]

@alandefreitas: This patch covers the current Capy needs but, as I said on Slack, it is ad-hoc. The only long term solution is what Vinnie suggested: a Clang hook to take over comment processing entirely. A bit reluctantly, given the time I spent on it, I'd say we shouldn't merge it. We can extract the fix to inline.html.hbs from it, though, which is a genuine bug fix and doesn't depend on the Clang hook.

---

Markdown inline formatting (bold, italic, code) and bullet lists using "- " markers were not rendered in the HTML output.

Inline formatting:

• Add appendMarkdownInlines() to parse bold, italic, and code spans in text nodes, producing StrongInline, EmphInline, and CodeInline nodes respectively.

• Call it from visitText() so all text nodes are processed.

• Add a markup/b.html.hbs partial to render <strong> tags.

• Add doc/inline.html.hbs to dispatch text, strong, emph, and code inline kinds to their partials without emitting extraneous blank lines.

List detection and conversion:

• Add list marker detection functions that recognize "- " at the start of text, after newlines, after ":" or "." punctuation, and at trailing positions within already-started lists.

• Add convertParagraphWithLists() to split a paragraph containing list markers into a prefix paragraph and a ListBlock.

• Apply list detection in visitParagraph(), @par blocks, and @li blocks so that Markdown lists are converted in all contexts.

[github-actions]

🚧 Danger.js checks for MrDocs are experimental; expect some rough edges while we tune the rules.

✨ Highlights

• 🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	740	736	4	6	4	2	-	-
🛠️ Source	266	259	7	8	2	6	-	-
🏗️ Build / Toolchain	2	1	1	1	-	1	-	-
Total	1008	996	12	15	6	9	-	-

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

🔝 Top Files

• test-files/golden-tests/javadoc/markdown-list/markdown-list.html (Golden Tests): 281 lines Δ (+281 / -0)
• test-files/golden-tests/javadoc/markdown-list/markdown-list.adoc (Golden Tests): 215 lines Δ (+215 / -0)
• src/lib/Metadata/Finalizers/DocCommentFinalizer.cpp (Source): 195 lines Δ (+195 / -0)

Generated by 🚫 dangerJS against e4a8e44

[cppalliance-bot]

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

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

2026-02-10 11:40:34 UTC

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.47%. Comparing base (5426a0a) to head (e4a8e44).

Files with missing lines	Patch %	Lines
...rc/lib/Metadata/Finalizers/DocCommentFinalizer.cpp	94.52%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1157      +/-   ##
===========================================
+ Coverage    76.38%   76.47%   +0.09%     
===========================================
  Files          311      311              
  Lines        29672    29751      +79     
  Branches      5863     5882      +19     
===========================================
+ Hits         22664    22753      +89     
+ Misses        4735     4728       -7     
+ Partials      2273     2270       -3     

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

🚀 New features to boost your workflow:

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

[alandefreitas]

The only long-term solution is what Vinnie suggested: a Clang hook to take over comment processing entirely

Yes. In theory, we could just bypass clang and parse everything ourselves, and this would be somewhat equivalent to a hook. The biggest issue blocking this right now is human resources: the current plan is to address #1113 first (although we're opening this exception for capy issues). We'll have reasonable solutions for the parsing problem once we get it. 😊

[alandefreitas]

Oh... Regarding your solution, it looks a little verbose (and potentially duplicated), to be honest. 😅

We already parse Markdown elsewhere in the finalize step; this is completely unrelated to the clang parser. The algorithm takes an array of text nodes and converts them inline into nodes with the proper tags (there are even unit tests for that). We just need to complete the plumbing so that the list items also work with this functionality. It shouldn't be much code.

The impression I have is that whatever procedure you used to figure out what to change wasn't aware that the logic already exists in the codebase. And that's understandable, because this codebase has become extremely large and complex, and it's hard to understand the context in which each thing happens. 🙃

But we can come up with a reasonable solution to this problem. It's not that bad. Oh... and we also need tests, of course. 🙂