MDX Cheat Sheet and Quick Reference Guide

Good technical documentation tells and shows users how to use your software. MDX does a great job at the “show” part of documentation by allowing writers to embed interactive examples within Markdown documents.

But MDX syntax isn’t always straightforward. In this article, we will review an MDX cheat sheet to help you with common use cases and troubleshooting while you create or build on existing MDX documents.

What is MDX and why should you use it?

Markdown has long been the standard document language for creating technical documents. It reads and writes like English, but renders as web pages. The light syntax and basic text structure make Markdown an excellent tool for any technical writer.

As the web got more complex, users needed more interaction from their documents. This is where MDX found its footing. MDX is Markdown that can embed JSX or JavaScript components directly in documents.

MDX documentation allows more interactivity by placing code examples directly in documents. These examples include interactive components, results from endpoint calls, and live data. All of this is available directly in the Markdown docs, extending the functionality of documents immensely.

MDX’s key features

What are some of the key features of MDX? They include:

Extending Markdown which allows the reuse of existing documents
Support for JSX (JavaScript components)
Allowing for importing and exporting of components across documents

Because MDX is a superset of Markdown, you can convert all valid Markdown files to MDX simply by changing the file extension from ‘.md’ to ‘.mdx.’ This makes migrating your existing documents to MDX quick and easy.

Figure 1. Markdown to MDX file extensions

MDX excels at making Markdown documents more interactive. Instead of just telling users how they can use an endpoint or a component, MDX allows writers to show items in action.

With MDX, technical writers display the exact features their products offer and bring documents to life through live examples.

MDX is also great at making documents DRY, which is a popular software acronym that stands for Don’t Repeat Yourself.

Because MDX supports import and export statements in Markdown documents, this allows you to create modular, reusable components. You build these components once and share them across entire document sets.

Figure 2. Import components to JSX component

This reduces the copying and pasting of code snippets in Markdown files and makes updating documents as simple as changing one file.

MDX vs. Markdown

Now that you understand MDX, let’s take some time to review the differences between Markdown and MDX.

Feature	Markdown	MDX
Basic Syntax	Uses standard Markdown for headings, lists, and formatting.	Supports standard Markdown syntax.
JSX Support	Not supported.	Allows embedding JSX components inline.
Dynamic Content	Limited to static content.	Can use JavaScript expressions inside {} for dynamic content.
Imports & Exports	Not supported.	Supports import and export statements for modularity.

From this table, you can see that both languages use Markdown as a base. MDX extends Markdown by supporting dynamic content using JSX components. These components are shareable with your team across entire document bases.

MDX integrations with popular frameworks

One consideration when switching from Markdown to MDX is that MDX is not basic text. MDX is a combination of Markdown text with JavaScript components, so your browser can’t natively read these documents and you need a compiler to make the .mdx files readable.

Luckily, many popular front-end frameworks support MDX natively. If you’re looking to use MDX in your project, you can turn to NextJS or Gatsby as out-of-the-box solutions for writing and serving MDX documents.

MDX Cheat Sheet

MDX may be more complicated to work with than Markdown, but it does not have a steep learning curve. Let’s go over some of the basics that will get you from a seasoned Markdown writer to a successful MDX author.

How to write a simple MDX document

If you are comfortable writing Markdown, you are already well on your way to writing MDX. MDX simply extends Markdown by adding the ability to insert JSX or JavaScript components.

Let’s take a look at a basic MDX example. Imagine that we are writing API documentation for a user endpoint that allows us to receive the name, occupation, and city of a user given their user ID. We describe the endpoint and then make a call to get a JSON response.

In the MDX docs, we import a JSX component, APICall, at the top of our MDX file. We then embed it directly in our markdown file. We show the response of our call and pass the response values to APICall to show a user card.

We can see this in the code below:

# MDX example code (Markdown for importing components and making API calls)

import { APICall } from ‘../components/APICall’;

# Get User Information Retrieve user details by sending a `GET` request to the following endpoint:

“`http GET /user/{id}

# A successful response for id of 1

“`{ “fullName”: “John Doe”, “occupation”: “Software Engineer”, “city”: “San Francisco” }

# JSX Component showing UI components to make with JSON response

How to format MDX code for readability

Above, we showed how to embed an imported JSX component in our MDX file, but what does a JSX component look like? Good components should have proper indentation and consistent variable naming. Let’s take a closer look at our APICall component:

# APICall JSX Component

export function APICall({ fullName, occupation, city }) {

return (

<h3>User Details</h3>

<p><strong>Full Name:</strong> {fullName}</p>

<p><strong>Occupation:</strong> {occupation}</p>

</div>

);

}

Here we see indentation for each of the levels of the HTML components. This makes it easier to read the JSX. The variable names use Pascal casing and are meaningful so we know what the values should represent.

How to work with components and props

What are the items we’re passing into the JSX component? Let’s look at APICall again:

The values of fullName, occupation, and city are called props. These properties are passed into a JSX component to customize it with specific values. Possible props include text to be displayed, color and style options, or even entire JSON objects.

JSX components allow us to make our code modular and reusable. Props allow us to add customization to these components. If you are interested in learning what props are available, you can look at the head of the component to see all the prop options.

Here is the head of our APICall component, where you can see three possible props: fullName, occupation, and city.

export function APICall({ fullName, occupation, city }) {

Even if you aren’t writing components, it’s helpful to understand props to know how to extend or customize the components in your MDX documents.

MDX troubleshooting

One of the main drawbacks of MDX is its added complexity. While technical writers don’t need to be able to write JSX components, they need basic MDX literacy to work with components.

As a technical writer, you should not be expected to fix the JSX code. However, you should be able to troubleshoot and discuss the issues you see with your MDX files. Let’s review some issues you might run into and how to identify their root causes.

Handling JSX conflicts in MDX files

Markdown files consist of syntax that gives meaning and style to text, lists, and headers. There are no conflicts within these files. However, using MDX can have conflicts due to its integrated JavaScript.

There are many reasons why JavaScript files may have conflicts. Two of the most common are:

Misuse of keywords
Syntax errors

MDX uses JavaScript syntax which includes keywords such as class, let, const, and return. Misusing these keywords will produce errors and break your MDX file. Syntax errors will also have the same result.

You can identify and solve both of these issues by using an interactive development environment (IDE). This tool is useful for managing project files and integrating language support libraries which include linting and syntax error highlighting.

SEO impact of MDX components

Markdown is great for SEO performance thanks to its server-side rendering. Server-side rendered pages are documents that are fully formed on the server before being sent to the user. This way of transporting data allows web crawlers and search engines to see all of your page data at once.

MDX components are client-side rendered. Client-side rendered pages don’t show their content until after the page has been loaded. This impacts a search engine’s ability to access page content.

If you put too much of your page data into the JSX component instead of in the Markdown file, you might negatively impact your SEO.

To avoid this, use Markdown for lists, headings, and text. Avoid moving this type of text data into MDX components unless absolutely necessary. By allowing the search engine-friendly data to load in your Markdown, your pages will see more traffic.

Avoiding performance issues with large MDX files

Another common issue when working with MDX files is performance, which occurs when requests or page loads take too long. Amazon is famous for correlating an extra second of page load time to over a billion dollars of lost revenue every year.

The two main culprits for MDX performance issues are loading all the page code at once and not optimizing component code.

You can solve the first issue with lazy loading, which is the process of loading web page content on demand.

When a page loads, you only see the content on the screen, or above the fold. To be able to see more, you will need to scroll down. The idea is that the content at the end of the page is not immediately needed, so we should load it later. To help with lazy loading components, you can use libraries and even internal support from React.

Non-optimized code is harder to diagnose because it could be caused by anything from loading in extra code to making inefficient calls and unnecessary component rerenders.

Meet with your developers to discuss code optimization if you fix the lazy load issue and suspect non-optimized code as the main culprit.

MDX use cases

The great thing about MDX is that with JSX, our documents come to life. We are not restricted to writing static, academic-feeling papers. Instead, we can support any documentation from basic text files to interactive blogs and product pages.

Using MDX in interactive API documentation

MDX is great for API documentation. The JSX components allow us to go beyond describing endpoints, and we can make calls and populate UI elements to give users an idea of what they can do with our endpoint responses.

Figure 4. ReadMe docs showing MDX components for writing API documentation

If you’re using an API documentation platform like ReadMe, then you can use an MDX-supportive web-based editor. it natively supports MDX and even offers prebuilt components to make your API documents great.

These components can contain tabs, accordions, and cards that better organize your data. They can also include charts and graphs to display real-time data or other UI elements to showcase real-world applications, helping you make your API documentation easier to digest and more enjoyable to read.

Building dynamic content-driven websites with MDX

With MDX you can go beyond API or other technical documentation. With the JSX support, MDX turns Markdown into a templating engine that gives writers and developers the ability to build modern web pages.

Templating engines leverage the consistent structure of server-side rendered content with the dynamic nature of data-driven use cases. A great example is a store product page. Most product pages consist of text, lists, and headings, making Markdown perfect for this use case.

But what if you want to add an input form or show extra customization for a jacket or shoes? With MDX, you can create input forms to let users enter their preferred sizes, colors, or other product features.

Even better than just allowing users to select text options, you can show them their selection by conditionally rendering different product image sets. MDX templating takes static Markdown pages and brings them to life.

And you can do much more than just build product pages with MDX. You can also create interactive blogs and showcase API and developer products.

Next Steps with MDX

MDX doesn’t need to be intimidating. Following conventions with good JSX component formatting and variable naming makes writing MDX clearer. Performance issues can be solved by not adding extra logic to components or calling code before it’s needed.

Using the correct tools for your MDX documents is another way to increase your efficiency. Whether you’re looking to migrate your existing Markdown files to MDX or improve your current MDX workflow, you should check out ReadMe. The platform offers an intuitive and easy-to-use online editor that makes writing Markdown and MDX documents quick and pain-free.

Let’s Build Your Developer Hub