Skip to content

Fix nested list handling in Javadoc to AsciiDoc converter#53689

Open
kyooosukedn wants to merge 1 commit intoquarkusio:mainfrom
kyooosukedn:fix/nested-list-asciidoc-converter
Open

Fix nested list handling in Javadoc to AsciiDoc converter#53689
kyooosukedn wants to merge 1 commit intoquarkusio:mainfrom
kyooosukedn:fix/nested-list-asciidoc-converter

Conversation

@kyooosukedn
Copy link
Copy Markdown

Description

Fixes #50474

The JavadocToAsciidocTransformer previously flattened all nested HTML lists (<ul>/<ol>) to the same level, using the same marker for all items. This resulted in incorrect AsciiDoc output where nested bullet lists were indistinguishable from top-level items.

Example

This Javadoc:

/**
 * Some javadoc with list of lists:
 * <ul>
 * <li>First sentence. Second sentence.</li>
 * <li>
 * And some nested bullet list:
 * <ul>
 * <li>Element 1 with one sentence.</li>
 * <li>Element 2 with sentence 2.</li>
 * </ul>
 * </li>
 * </ul>
 */

Before (flattened):

Some javadoc with list of lists:

 - First sentence. Second sentence.
 -  And some nested bullet list:

 - Element 1 with one sentence.
 - Element 2 with sentence 2.

After (proper nesting):

Some javadoc with list of lists:

 * First sentence. Second sentence.
 * And some nested bullet list:
 ** Element 1 with one sentence.
 ** Element 2 with sentence 2.

Changes

  • Track list nesting depth in the Context class
  • Use AsciiDoc-standard nested list markers (* for unordered, . for ordered) repeated according to depth (e.g., ** for level 2, *** for level 3)
  • Strip leading whitespace from text nodes inside list items to handle HTML formatting artifacts
  • Avoid extra blank lines for nested lists (only top-level lists get trailing blank lines)
  • Updated existing test to match new marker style
  • Added 4 new tests:
    • parseJavaDocWithNestedUnorderedList - nested <ul> inside <ul>
    • parseJavaDocWithNestedOrderedList - nested <ol> inside <ol>
    • parseJavaDocWithDeeplyNestedLists - 3 levels of nesting
    • parseJavaDocWithMixedNestedLists - <ol> inside <ul>

The JavadocToAsciidocTransformer previously flattened all nested HTML
lists (<ul>/<ol>) to the same level, using the same marker for all items.
This resulted in incorrect AsciiDoc output where nested bullet lists
were indistinguishable from top-level items.

Changes:
- Track list nesting depth in the Context class
- Use AsciiDoc-standard nested list markers (* for unordered, . for
  ordered) repeated according to depth (e.g., ** for level 2, *** for
  level 3)
- Strip leading whitespace from text nodes inside list items to handle
  HTML formatting artifacts
- Avoid extra blank lines for nested lists
- Add tests for nested unordered lists, nested ordered lists, deeply
  nested (3 levels) lists, and mixed nested lists (unordered containing
  ordered)

Fixes quarkusio#50474
@geoand geoand requested a review from gsmet April 20, 2026 07:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

quarkus-config-doc-maven-plugin support for nested bullet list and multiple sentences in a bullet entry

1 participant