Rendering Errors: Invalid MDX

During the migration process, ReadMe attempts to automatically convert your Markdown to MDX. Some content is unable to be converted faithfully and may fail to render.

When that happens, you’ll see errors that look like the image below if you have invalid MDX and our parser is unable to render your page. Your customers will not see pages with errors in your doc’s navigation and will not be able to access the page’s content.

If you have HTML that is not compatible with JSX¹ (the syntax MDX is written in), you’ll need to rewrite some HTML. JSX is written similarly to HTML, but with some key differences.

📣

You can continue to write HTML in the HTML block. Any HTML outside the block, will need to be converted to JSX.

Closing Tags

JSX requires that every tag be closed explicitly. The most common issue when converting Markdown to MDX is updating any self-closing tags for void elements² . Here are a few of the most common examples:

<br>

<img>

<hr>

<br />

<img />

<hr />

In HTML, some end tags are optional. These are also required to be closed explicitly.

<p> YOUR CONTENT

<ul>
  <li>1
  <li>2
  <li>3
</ul>

<option>Small owl
<option>Large owl

<p> YOUR CONTENT </p>

<ul>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ul>

<option>Small owl</option>
<option>Large owl</option>

Attributes

HTML attributes must be written in camel case³ . And some attributes conflict with reserved words in JavaScript and have different names. For example, the class attribute is className in JSX.

<img class="my-image">

<svg>
  <circle stroke-width="1" />
</svg>

<img className="my-image" />

<svg>
  <circle strokeWidth="1" />
</svg>

The style attribute’s value must be written as a JavaScript object⁴ with camel case properties.

<p style="background: red; text-align: center;">

<p style={{ background: 'red', textAlign: 'center' }}></p>

Exception: aria- and data- attributes are unchanged from HTML.

<span aria-label="close" />

Comments

JSX also has a different syntax for comments. Any HTML comments will be escaped and displayed as paragraph text in your docs. ReadMe will continue to strip comment content from your markup.

<!-- COMMENT -->

{/* COMMENT */}

Variables

Our variable syntax has changed, and will instead use a JavaScript object syntax for using variables.

<<variable>>

{user.variable}

Invalid HTML

Writing invalid HTML in your markup won’t render in your docs, and cause render errors in MDX. They can be escaped to appear as plain text (written as /<world>) or need to be removed.

Hello <world>!

🖐️

Additional Tips

You can use an online converter to convert HTML to JSX. And you can always reach out to [email protected] if you need help or have questions.

[1] JavaScript Syntax eXtension lets you write HTML-like markup in JavaScript

[2] Void elements are HTML elements that cannot have any child nodes MDN List of void elements

[3] Camel case is a way of writing phrases without spaces or punctuation. The first word starts with lower case, and subsequent ones in uppercase. For example: backgroundColor and strokeWidth

[4] Objects in JavaScript are enclosed in curly braces {} and contains properties as a key-value pair. For example: { color: 'indigo' }