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

[gennaroprota]

Note: The comments below are out of date. Please refer to the PR commits for up to date info.

@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	1243	1229	14	8	4	4	-	-
🛠️ Source	371	297	74	7	2	5	-	-
Total	1614	1526	88	15	6	9	-	-

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

🔝 Top Files

• test-files/golden-tests/javadoc/markdown-list/markdown-list.xml (Golden Tests): 656 lines Δ (+656 / -0)
• src/lib/Metadata/Finalizers/DocCommentFinalizer.cpp (Source): 334 lines Δ (+264 / -70)
• test-files/golden-tests/javadoc/markdown-list/markdown-list.html (Golden Tests): 281 lines Δ (+281 / -0)

Generated by 🚫 dangerJS against fa3ff19

[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-03-09 17:12:12 UTC

[codecov]

Codecov Report

❌ Patch coverage is 92.78351% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.14%. Comparing base (9a5bd3c) to head (fa3ff19).
⚠️ Report is 5 commits behind head on develop.

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

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1157      +/-   ##
===========================================
+ Coverage    77.02%   77.14%   +0.11%     
===========================================
  Files          310      310              
  Lines        28974    29043      +69     
  Branches      5781     5795      +14     
===========================================
+ Hits         22318    22404      +86     
+ Misses        4429     4420       -9     
+ Partials      2227     2219       -8     

☔ 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. 🙂

[alandefreitas]

Great