How to prevent MDX documents from automatically adding <p> tags when rendering text that includes line breaks inside existing <p> tags?

[inlann]

I noticed that when I add MDX documents to the Docusaurus blog, if I include a <p> tag with child elements and line breaks, the text content inside gets wrapped with an additional <p> tag.

Example:

             <section style={{textAlign: "justify", boxSizing: "border-box", visibility: "visible"}}>
              <p style={{whiteSpace: "normal", margin: "0px", padding: "0px", boxSizing: "border-box", visibility: "visible"}}>
               Recently,
               <span style={{color: "rgb(6, 82, 76)", visibility: "visible"}}>
                <strong style={{visibility: "visible"}}>
                 We
                </strong>
               </span>
               created a 
               <span style={{color: "rgb(6, 82, 76)", visibility: "visible"}}>
                <strong style={{visibility: "visible"}}>
                 new game
                </strong>
               </span>
               to play
              </p>
             </section>

It will be rendered as:

<section style="text-align: justify; box-sizing: border-box; visibility: visible;">
  <p style="white-space: normal; margin: 0px; padding: 0px; box-sizing: border-box; visibility: visible;">
    <p>Recently,</p>
    <span style="color: rgb(6, 82, 76); visibility: visible;">
      <strong style="visibility: visible;">
        <p>We</p>
      </strong>
    </span>
    <p>created a</p>
    <span style="color: rgb(6, 82, 76); visibility: visible;">
      <strong style="visibility: visible;">
       <p>new game</p>
      </strong>
    </span>
    <p>to play</p>
  </p>
</section>

This causes the paragraph, which should render on a single line, to be split into multiple lines due to the nested <p> tags.

I know I can edit the MDX manually to keep the text within the <p> tag on a single line, like this:

             <section style={{textAlign: "justify", boxSizing: "border-box", visibility: "visible"}}>
              <p style={{whiteSpace: "normal", margin: "0px", padding: "0px", boxSizing: "border-box", visibility: "visible"}}>Recently,<span style={{color: "rgb(6, 82, 76)", visibility: "visible"}}><strong style={{visibility: "visible"}}>We</strong></span>created a <span style={{color: "rgb(6, 82, 76)", visibility: "visible"}}><strong style={{visibility: "visible"}}>new game</strong></span>to play</p>
             </section>

Writing the content of the <p> tag on a single line prevents the automatic addition of nested <p> tags, allowing it to render correctly:

<section style="text-align: justify; box-sizing: border-box; visibility: visible;"><p style="white-space: normal; margin: 0px; padding: 0px; box-sizing: border-box; visibility: visible;">Recently,<span style="color: rgb(6, 82, 76); visibility: visible;"><strong style="visibility: visible;">We</strong></span>created a <span style="color: rgb(6, 82, 76); visibility: visible;"><strong style="visibility: visible;">new game</strong></span>to play</p></section>

The reason I haven't done this is that my entire MDX document is created by saving a webpage as a single MHTML file, then converting it to MDX using a Python script. I use BeautifulSoup4 for this process, and to improve the readability of the converted HTML, I call soup.prettify(), which formats each tag on a new line. This results in the extra <p> tags, as shown in my initial MDX code block. If I skip soup.prettify() and simply save str(soup), the HTML content in the MDX file is all on a single line, which makes it hard to read and maintain. I tried filtering out <p> tags in the script and merging their content onto a single line, but since the final step still requires converting soup to a string, I either end up with prettify() and lose the merging, or I keep everything on a single line, sacrificing readability.

My python script to merge <p> tags:

from bs4 import BeautifulSoup

html = """
<section style="text-align: justify; box-sizing: border-box; visibility: visible;">
  <p style="white-space: normal; margin: 0px; padding: 0px; box-sizing: border-box; visibility: visible;">
    Recently,
    <span style="color: rgb(6, 82, 76); visibility: visible;">
      <strong style="visibility: visible;">
        We
      </strong>
    </span>
    created a
    <span style="color: rgb(6, 82, 76); visibility: visible;">
      <strong style="visibility: visible;">
        new game
      </strong>
    </span>
    to play
  </p>
</section>
"""

def merge_paragraph_tags(target_tag):
    result = ""

    for child in target_tag.children:
        if child.name:
            inner_html = merge_paragraph_tags(child)
            attrs_str = ''
            for attr in child.attrs:
                if isinstance(child[attr], list):
                    attrs_str += f"{attr}=\"{' '.join(child[attr])}\""
                else:
                    attrs_str += f'{attr}="{child[attr]}"'
            result += f"<{child.name} {attrs_str}>" + inner_html + f"</{child.name}>"
        else:
            result += child.strip()

    return result

soup = BeautifulSoup(html, 'html.parser')

for p_tag in soup.find_all('p'):
    merged_content = merge_paragraph_tags(p_tag)

    # print(111, merged_content)

    p_tag.clear()
    p_tag.append(BeautifulSoup(merged_content, 'html.parser'))

# print(soup.prettify())
pretty_html = soup.prettify()
print(111, type(pretty_html))
print(str(soup))
print(soup.contents)
# print(''.join(soup.contents))

Is there a better solution, such as preventing MDX from automatically adding nested <p> tags?

[slorber]

This is a behavior that comes directly from MDX, that you should eventually discuss on the MDX repo directly.

Turns out this has already been reported multiple times, here are just a few references:

• mdx v2: New line inside DOM element (jsx) creates unnecessary paragraph mdx-js/mdx#1798
• Unable to parse p tag with newline mdx-js/mdx#2181
• <summary> is not recognized. mdx-js/mdx#2263

We don't want to diverge from standard MDX, but technically you could decide to write your own little remark plugin that de-duplicates the <p><p>text</p></p> to just <p>text</p>.

What you want is to transform this AST:

{
      "type": "mdxJsxFlowElement",
      "name": "p",
      "attributes": [],
      "children": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "value": "text"
            }
          ]
        }
      ],
}

To just this:

{
      "type": "mdxJsxFlowElement",
      "name": "p",
      "attributes": [],
      "children": [
            {
              "type": "text",
              "value": "text"
            }
      ],
}

Here's some pseudo-code to give you an idea of the remark plugin you could write:

import {visitParents, SKIP} from 'unist-util-visit-parents'

const updatedTree  = visitParents(tree, 'p', (p, parents) => {
  const parent = parents[0];
  if (parent.type === 'mdxJsxFlowElement' && parent.name === "p") {
    parent.children = p.children;
    return SKIP;
  }
})

---

Note our new HTML minifier coming with v3.6 will report these HTML markup problems. In my troubleshooting guide I gave another workaround based on React fragments: #10580

This does not duplicate paragraphs:

<p>
  <>content</>
</p>