Fix Nested Table Conversion in HTML-to-Markdown Process

[Wuhall]

Type: Bug Fix

Problem
The current process_tag function fails to properly handle nested tables during HTML-to-Markdown conversion, causing:

1. Complete loss of nested table structures
2. Flattened output that breaks document hierarchy
3. Unreadable Markdown table syntax

Root Cause
• Standard Markdown doesn't support nested tables natively

• Existing implementation forced flattening of all table structures

• Child tables were being parsed as regular table cells

Solution
Modified the table conversion logic to:

1. Detect nested table structures during HTML parsing
2. Preserve inner tables as raw HTML blocks
3. Convert outer tables to standard Markdown syntax
4. Maintain proper whitespace and formatting

Implementation Details
Key changes in process_tag:

def process_tag(node):
    # **Handle nested tables**
    if node.name == 'table' and 'table' in parent_tags:
        # If this table is nested within another table, return its HTML representation
        return str(node)

Test Case
Input HTML:

<p> </p>
<p> Test</p>
<table>
    <tr>
        <td>黄河</td>
    </tr>
    <tr>
        <td>长江</td>
    </tr>
    <tr>
        <td>
            <p>七、team</p>
            <table>
                <tr>
                    <td>
                        <p>no</p>
                    </td>
                    <td>
                        <p>name</p>
                    </td>
                    <td>
                        <p>sex</p>
                    </td>
                    <td>
                        <p>pos</p>
                    </td>
                    <td>
                        <p>pos</p>
                    </td>
                    <td>
                        <p>1</p>
                    </td>
                    <td>
                        <p>1</p>
                    </td>
                    <td>
                        <p>1</p>
                    </td>
                </tr>
                <tr>
                    <td>
                        <p>1</p>
                    </td>
                    <td>
                        <p>**</p>
                    </td>
                    <td>
                        <p>-</p>
                    </td>
                    <td>
                        <p>--</p>
                    </td>
                    <td></td>
                    <td>
                        <p>--</p>
                    </td>
                    <td>
                        <p>ITa</p>
                    </td>
                    <td>
                        <p>11</p>
                    </td>
                </tr>
                <tr>
                    <td>
                        <p>2</p>
                    </td>
                    <td>
                        <p>**</p>
                    </td>
                    <td>
                        <p>-</p>
                    </td>
                    <td>
                        <p>--</p>
                    </td>
                    <td></td>
                    <td>
                        <p>---</p>
                    </td>
                    <td>
                        <p>ITb</p>
                    </td>
                    <td>
                        <p>1</p>
                    </td>
                </tr>
            </table>
        </td>
    </tr>
    <tr>
        <td>
            <p>11：</p>
            <p>22： </p>
            <p> </p>
            <p> date：</p>
        </td>
    </tr>
</table>

Previous Output (Broken):

Test

黄河
长江
七、team
11： 22： date：

---

New Output (Correct):

Test

黄河
长江
七、team no name sex pos pos 1 1 1 1 - -- -- ITa 11 2 - -- --- ITb 1
11： 22： date：

[chrispy-snps]

@Wuhall - thank you for your contribution! However, I am not sure I agree with this change for the following reasons:

• Many (most?) users want to convert the HTML input entirely to Markdown, with no HTML remaining.
• Table cells can contain a variety of structured content beyond tables - tables, lists, definition lists, preformatted blocks, blockquotes.
• It is easy to subclass Markdownify to get the specific behavior you need for your use case.

@AlexVonB, what do you think?

[Wuhall]

@chrispy-snps thanks for your feedback! I completely understand the concern about keeping Markdown output clean and portable. Here’s a compromise that might address both sides:

1. User-configurable behavior:
   • Add an optional parameter (e.g., nested_tables=False) to allow users to explicitly opt-in for nested table conversion.

   • Default behavior remains unchanged (strip nested tables), ensuring backward compatibility.

2. Why this helps:
   • Many users do need nested structures (e.g., Confluence/Notion exports, technical docs), and currently, they lose data silently.

   • A subclass workaround is possible, but it’s less discoverable than a built-in option.

3. Implementation flexibility:
   • The conversion could either:

   ◦ Preserve nested tables as HTML (if nested_tables=True), or

   ◦ Use indented Markdown pseudo-tables (if feasible).

I’d love to hear your thoughts on this approach! If acceptable, I can update the PR with these changes.

[ayushxx7]

It is important to note that this issue would directly impact the markdownify app launched from microsoft. Kinda makes it an important issue to resolve quickly especially since the user has solver most of the problem. Ref: microsoft/markitdown#1248 (comment)

[Wuhall]

There is an unexpected conflict in my branch. I will fix this conflict and re-PR. Ref:220