Skip to content

fix(markdown): indent the block children of a list item - #888

Open
pandasuwu wants to merge 2 commits into
docling-project:mainfrom
pandasuwu:fix/md-list-item-block-indent
Open

pandasuwu wants to merge 2 commits into
docling-project:mainfrom
pandasuwu:fix/md-list-item-block-indent

Conversation

@pandasuwu

@pandasuwu pandasuwu commented Oct 17, 2026 •

Copy link
Copy Markdown

The Markdown list serializer indents only nested lists. Other children of a ListItem (code, tables, formulas, pictures, text) are written at the indentation of the item marker. A CommonMark parser then ends the item before them. When the item has no text, the parser reads an empty item, and the next item starts a new list with its own numbering.

Example from the LaTeX backend (docling-project/docling#4518):

\begin{enumerate}
\item \begin{verbatim}code\end{verbatim}
\item Second
\end{enumerate}

Before:

1. 
```
code
```
2. Second

A CommonMark parser reads an empty item 1., a code block outside the list, and a new list that starts at 2..

After:

1. 
   ```
   code
   ```
2. Second

Fix. Each line of a non-list child of a list item is indented to the content of that item, that is, by the width of the item marker: 2 for -, 3 for 1., 4 for 10.. Blank lines are not indented, so a code block keeps its blank lines. Nested lists keep their own indentation, as before.

Tests. Four new tests in tests/test_serialization.py, all failing on main:

  • test_md_list_item_block_children_are_indented: an empty item with a code block (with a blank line) and text, and an item with text and a formula.
  • test_md_list_item_block_children_follow_marker_width: a code block under - and under 10..
  • test_md_nested_list_item_block_children_are_indented: a code block in a nested item, and one after the nested list.
  • test_md_list_item_table_with_caption_outside_list_is_indented: a table in an item whose caption is not in the list, so the serialized table starts with an item from outside the list.

Regenerated with DOCLING_GEN_TEST_DATA=1: no Markdown ground truth changes.

Downstream. I regenerated the docling ground truth of the non-ML backends with this branch. Compared with docling-core main, only these change: a picture inside a list item is now indented into its item in asciidoc_03.asciidoc.md, html_nested_block_in_list_item.html.md and wiki_duck.html.md, and one continuation line of a list item in the LaTeX 2305.03393_main.tex.md.

The Markdown list serializer indented only nested lists. Other children
of a list item (code, tables, formulas, pictures, text) were written at
the indentation of the item marker, so a CommonMark parser ended the item
before them. An item without text was read as an empty item, and the
next item started a new list with its own numbering.

Each line of such a child is now indented to the content of its item,
that is, by the width of the item marker. Nested lists keep their own
indentation.

Signed-off-by: pandasuwu <suhani.m024@gmail.com>
@github-actions

Copy link
Copy Markdown
Contributor

✅ DCO Check Passed

Thanks @pandasuwu, all your commits are properly signed off. 🎉

@mergify

mergify Bot commented Oct 17, 2026

Copy link
Copy Markdown
Contributor

Merge Protections

🔴 1 of 2 protections blocking · waiting on 👀 reviews

Protection Waiting on
🔴 Require two reviewer for test updates 👀 reviews
🟢 Enforce conventional commit —

🔴 Require two reviewer for test updates

Waiting for

  • #approved-reviews-by >= 2
This rule is failing.

When test data is updated, we require two reviewers

  • #approved-reviews-by >= 2

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

  • title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

pandasuwu added a commit to pandasuwu/docling that referenced this pull request Oct 17, 2026
A theorem, verbatim, lstlisting or tabular at the start of an enumerate
item is exported as an empty item followed by the block at column 0, so
a CommonMark parser ends the list. The fix is in docling-core
(docling-project/docling-core#888); the test is xfail until it is bumped.

Signed-off-by: pandasuwu <suhani.m024@gmail.com>
A serialized table or picture can start with its caption. When the
caption is not in the list (for example a caption at body level), the
first span of the part did not lead to a list item, so the block was not
indented and ended the list. Use the first span that is in the list.

Signed-off-by: pandasuwu <suhani.m024@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants