Paragraphs in MDX

Paragraphs are the most fundamental building block of any written content. In MDX, they work exactly like they do in standard Markdown — you just write text, and it becomes a paragraph. No special syntax needed. However, understanding the spacing rules deeply will save you countless debugging sessions when your content does not render the way you expect.

Let us walk through everything you need to know about paragraphs, line breaks, and whitespace behavior in MDX.

Why Adjacent Lines Merge

This behavior exists because of how Markdown was designed. The creators wanted you to be able to write in a text editor with a fixed width (like 80 characters per line) and have the text reflow naturally in the output. So line breaks in your source file are treated as spaces, not as actual line breaks in the output.

This line and this line and this line too all become one paragraph.

They render as a single continuous paragraph with spaces between the words. The newlines in your source are converted to spaces.

Line Breaks (Without a New Paragraph)

Sometimes you want a new line but NOT a full paragraph gap. You want a <br> tag — a line break within the same paragraph. There are two ways to achieve this:

Option 1: Two spaces at the end of a line

(The ·· represents two space characters at the end of the line.)

Those two trailing spaces force a <br> tag. The lines render on separate lines but within the same <p> element — so the spacing between them is smaller than between separate paragraphs.

Option 2: Use the <br /> tag directly

This is more explicit and easier to see in your source code. I recommend this approach because invisible trailing spaces are extremely easy to miss, and many code editors strip trailing whitespace automatically.

Option 3: Backslash at end of line (some parsers)

Some Markdown parsers support a backslash at the end of a line as a line break. This works in many MDX configurations but is less universally supported than the other two options.

Spacing Around Other Elements

Paragraphs do not exist in isolation. They sit between headings, code blocks, lists, components, and other elements. The blank line rule applies to all transitions:

After Headings

Always leave a blank line after headings. Without it, some parsers may merge the text with the heading or produce unexpected formatting.

Before and After Code Blocks

Always leave blank lines before and after code blocks. This ensures the parser correctly identifies where the code block starts and ends.

Before and After Lists

Lists need blank lines before and after them to be properly parsed as separate elements from surrounding paragraphs.

Paragraphs and React Components in MDX

This is where MDX adds complexity. When mixing paragraphs with React components, the blank line rule becomes critical:

Always leave blank lines around components. Without them, the MDX parser may not recognize the component as a block-level element. It might try to treat it as inline content within the paragraph, causing compilation errors or unexpected rendering.

Inline Components Within Paragraphs

If you want a component inside a paragraph (inline), do NOT use blank lines:

Here, StatusBadge renders inline within the paragraph text because there are no blank lines separating it.

Common Mistakes and How to Fix Them

1. Forgetting the blank line after headings

Fix: Always add a blank line between a heading and the following content.

2. Unintended trailing spaces

Some editors auto-add trailing spaces when you press Enter. If your text has unexpected line breaks in the rendered output, check for invisible trailing spaces at the end of lines. Configure your editor to show whitespace characters.

3. Indenting regular paragraphs

Never indent regular paragraph text. Four spaces of indentation is the Markdown syntax for a code block.

4. Missing blank lines around components

This will likely cause parsing errors. Always surround block-level components with blank lines.

5. Expecting single newlines to create visible breaks

New developers often expect each line to appear on its own line in the output. It will not — it renders as "Line one Line two Line three" all in one paragraph. Use blank lines for paragraphs or <br /> for line breaks.

How Paragraphs Render in HTML

When MDX compiles your content, each paragraph becomes a <p> element:

The visual spacing between paragraphs is controlled by CSS — typically margin-bottom on the <p> element. Most MDX-powered sites apply a margin of around 1rem to 1.5rem between paragraphs.

Line breaks (<br />) render as:

Best Practices for Writing Paragraphs

• Keep paragraphs focused. Each paragraph should cover one idea. When you shift topics, start a new paragraph.
• Watch your line length in source. Many style guides recommend keeping source lines under 80-100 characters and letting the browser handle wrapping.
• Use blank lines generously. When in doubt, add a blank line. Extra blank lines between elements never hurt, but missing ones cause bugs.
• Do not indent paragraph text. Indentation in Markdown has meaning — it creates code blocks or continues list items.
• Be consistent with line break style. Choose either trailing spaces or <br /> and stick with one approach across your project.

Quick Reference

That covers everything about paragraphs in MDX. It is a simple topic on the surface, but getting spacing right is the difference between content that renders cleanly and content that produces mysterious compilation errors.