HTML <p> Tags in Table Cell Merged Incorrectly in Markdown

[MahmoudAtef4499]

Bug Description

When converting HTML tables to Markdown, if a table cell contains multiple <p> tags, the output merges their content without spacing, resulting in incorrect values.

Example:

This HTML cell:

<td><p>3</p><p>1</p></td>

is currently converted to:

| 31 |

instead of preserving the structure like:

| 3<br>1 |

or:

| 3  
  1 |

---

Expected Behavior

• The Markdown converter should preserve the semantic line breaks or paragraph separations within a table cell.
• Multiple <p> tags should not be flattened into a single string with no delimiter.

---

Current Behavior

• The converter merges multiple <p> tags into one line, resulting in values like 31 instead of maintaining their structure or indicating separation.
• This misrepresents the actual data from the HTML source.

Environment

• Python: 3.12
• Docling version: Latest

I will attach the HTML file that reproduces the issue.

174627142405997939927c_page_111.zip

Thank you very much in advance for your time and support.

[dosubot]

Hi @MahmoudAtef4499! I'm Dosu and I’m helping the docling team.

This merging issue happens because the Markdown backend currently concatenates the contents of multiple <p> tags in a table cell without any separator—there’s no logic to insert line breaks or <br> tags between them. The relevant code is in the MarkdownDocumentBackend class, specifically the _iterate_elements and _close_table methods, which handle table parsing and serialization but do not preserve paragraph boundaries within cells (source).

To fix this, you’d want to update the logic that collects and serializes table cell content so that when multiple paragraphs are detected, they are joined with a Markdown line break (<br>) or two spaces and a newline. This would involve modifying how _iterate_elements gathers content for each cell and how _close_table outputs it. There are no config options or extension points for this right now, so a code change is needed.

If you want a quick workaround, you could preprocess the HTML to replace consecutive <p> tags inside <td> with <br>-separated text before conversion, but a proper fix should go into the backend’s table cell handling logic.

Let me know if you want a sample patch or more detailed guidance on where to make these changes!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[MahmoudAtef4499]

Hi @dosu,

Thank you so much for the detailed explanation — that really clarified the cause of the issue.

Yes, I’d appreciate it if you could point me more specifically to where the changes should be made inside the MarkdownDocumentBackend class, especially in the _iterate_elements or _close_table methods.
A brief guide or even just the relevant lines would be very helpful to get me started.

Thanks again for your support!

[cau-git]

@MahmoudAtef4499 This is mostly coming down to a design choice: Pure markdown can not have line breaks in table cells. Injecting HTML tags into Markdown is making it non-pure. We have the concept of serializers, which can be customized to achieve the desired output, see here.

@dosu Feel encouraged to advise how to create such a serializer modification or option.

[dosubot]

To customize how Docling serializes Markdown tables—specifically to handle multiple

tags in a cell with line breaks or
tags—you'll want to subclass MarkdownTableSerializer and override its serialize method. The default implementation flattens all newlines in cell text to spaces, so paragraph structure is lost. By customizing this, you can join cell content with
or Markdown line breaks as needed. See the relevant code here.

Here's a sketch of what you might do:

from docling_core.transforms.serializer.markdown import MarkdownTableSerializer
from docling_core.types.doc.document import TableItem
from tabulate import tabulate

class CustomMarkdownTableSerializer(MarkdownTableSerializer):
    def serialize(self, *, item: TableItem, doc_serializer, doc, **kwargs):
        # Custom logic: replace a custom delimiter (e.g., '\n\n' or a marker) with '<br>'
        rows = [
            [
                col.text.replace('\n\n', '<br>')  # or your preferred delimiter
                for col in row
            ]
            for row in item.data.grid
        ]
        # ...then continue as in the base class
        table_text = tabulate(rows[1:], headers=rows[0], tablefmt="github") if len(rows) > 1 else ""
        return doc_serializer.create_ser_result(text=table_text, span_source=item)

To use your serializer, inject it into your workflow by subclassing MarkdownDocSerializer or by providing it via a serializer provider (see the serializer provider mechanism). For example, in a chunker or export pipeline, you can specify your custom serializer so Docling uses it for Markdown output.

Keep in mind: pure Markdown tables do not support line breaks in cells, so this approach will inject HTML (<br>) or use Markdown's double-space linebreaks, which may not render in all Markdown viewers. If you want to keep your Markdown "pure", you may need to preprocess your data to use double spaces and a newline instead of <br>.

For more on integrating custom serializers, see the advanced chunking and serialization example.

Let me know if you want a more detailed code sample or guidance on integrating this into your workflow!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[MahmoudAtef4499]

Hi @cau-git,

Thank you for the explanation.

I understand the importance of keeping the Markdown output pure. However, in the case where a table cell contains multiple paragraphs like <p>3</p><p>1</p>, I believe the content should at least be separated by a space or two, rather than being merged into a single string like 31.

This merging can cause confusion or misrepresentation of the original data.

I'd appreciate guidance on how to customize the serializer to ensure such paragraph separation — even just by adding a single space or double space between paragraphs inside a cell.

Thanks again!