Home

MDX Explained: The Ultimate Guide to Extended Markdown

What is MDX?

MDX is a file format that allows developers to use both Markdown and JSX syntax together. When you write an MDX file, you can include Markdown syntax for simple text formatting, such as headings, lists, and links, as well as JSX syntax for more complex UI components. It stands for "Markdown eXtended" and is commonly used for documentation in React based projects.

Overall, MDX makes it easier to create rich and interactive content that combines the simplicity of Markdown with the power and flexibility of JSX.

Rendered MDX

How does MDX work?

MDX works by setting up a preprocessor inside your front-end framework of choice. This can then be used to easily convert your MDX files into plan HTML/JavaScript files that can be displayed by your application.

MDX files are normally preprocessed into HTML/JavaScript at build time (before your application is deployed) - meaning the conversion from MDX does not affect the performance of your application.

Features of MDX

MDX provides many new features over traditional markdown, including:

1) JavaScript Expressions

You can use JavaScript in-line to dynamic calculate values. For example, the following line would render as: 2023 (the current year).

{new Date().getFullYear()}

2) JSX Components

JSX is the JavaScript extension commonly used by React in order to render components on the page. As MDX has full JSX support, you can add normal React-based components into your markdown page. JSX has a full ecosystem of existing components which you can import directly into your MDX pages. Common use-cases for JSX components would be to include YouTube video embeds or syntax highlighting inside your MDX page.

YouTube Embed Component

3) Customisable

As MDX renders directly as html components, each default html component is entirely customisable. For example, all headings can be overwritten with a custom header component to add extra functionality with the following code:

components={{h1: MyCustomHeading}}

A common use-case for overriding default html components, is to override the default link component (<a>) and replace it with a custom link that opens external links in new tabs while opening internal links within the same browser tab. I've got an existing tutorial here on how to do that.

4) Markdown Based

Markdown is a common markup language used by software developers for documentation. It's simple to write and easy to include code snippets or tables. Due to MDX being based on Markdown, all existing markdown docs can start using MDX by changing the file extension from .md to .mdx. MDX is easy to write and can still benefit from existing markdown-based editors such as Obsidian.

5) Rehype & Remark Plugins

MDX functionality can be expanded using both Rehype & Remark plugins. These can be used to transform your mdx content and add additional functionality. For example, adding syntax highlighting for code snippets, using remark-mdx-chartjs to add charts & graphs to your site or using remark-gfm to allow GitHub flavoured markdown features such as tables or tasklists.

6) Speed

As MDX is rendered into HTML at build time (rather than runtime), it is as quick as any html page. Writing in MDX has no negative performance impact on your site and usually the pages can be statically generated (rather than server side rendered), meaning they are lightweight and performant.

When to use MDX?

MDX shouldn't be used on every page in your site. Instead it should be used on “content-based” pages such as blog posts, news articles or tutorials. These are pages where the user is focused on the content itself rather than the look & feel or functionality of the page. MDX wouldn't be suited for “main” pages of your site (Home, About, Contact Us).

MDX instead of PowerPoint?

Using MDX Deck, you can actually create presentation decks using solely markdown and JSX components. This package comes with pre-built themes, requires zero configuration and has normal presentation features such as "Presenter Mode" & "Speakers Notes".

MDX Deck - Presentations with MDX

How to setup MDX?

MDX can be used in any JSX runtime such as React or Vue or a React based front-end framework such as Next.JS or Gatesby.

Depending on your framework choice, there are many ways you can setup and use MDX inside your application.

Frontmatter

Just like in normal markdown files, Frontmatter can be used to add Metadata to our MDX files. This metadata is stored in YAML at the top of the mdx file, and any key-value pairs can be used. In a MDX based blog, you might use frontmatter to store the blog's title, description and cover image so that a preview of the blog can easily be displayed on a different page:

---
title:  "MDX Explained: A Comprehensive Guide to Extended Markdown"
date: '27 April 2023 17:11'
description: Learn all about MDX (Extended Markdown)
image: "/blog/meta/mdx-ultimate-guide.png"
---

Using a package such as grey-matter, you can easily split the metadata from the page content to use within your application. MDX Metadata can also be used to set meta tags on your MDX pages in order to increase the SEO of your page.

Styling MDX with TailwindCSS

By default MDX is rendered as normal HTML elements (<h1>, <h2>, <a>, <p>), however by default these elements have no styling. This means that your site is then rendered as black and white text on a page.

You could spend the time styling every element individually however this takes time to ensure every item looks good together and is mobile responsive.

Instead, you can use the Typography Plugin from TailwindCSS which provides automatic styling of rendered markdown in a variety of colour schemes.

It's very simple to install and requires you simply add the prose css className to the root div of your mdx page.

Click here to setup TailwindCSS Typography with Next.js.

TailwindCSS Typography

MDX with a Content Management System

MDX can be stored inside a CMS (Content Management System) and pulled into your application via APIs. You can use a headless CMS such as Contentful or even a non-traditional CMS such as Notion or Obsidian.

Pros & Cons of MDX

As you can see from the table below, other than initial setup, there really is no reason why you shouldn't be using MDX.

ProsCons
MDX is Fast - It renders/compiles at build-time rather than at runtimeSetup is Required - Frameworks such as Next.js have MDX support, but setup is required.
Extendable - Functionality can be added via either JSX Components or Rehype/Remark Plugins
TailwindCSS Support - Automatic styling of your MDX components using the prose class from the TailwindCSS Typography plugin.

MDX is a great tool that I personally have used on this site to create these blog posts. If you wish to get started with MDX using Next.js then take a look at these blogs below.