MDX Cheatsheet

The Purpose of This Reference

I created this document as a central repository for everything related to the MDX configuration used in this project. When building a content heavy site, it is easy to forget the specific syntax for a custom component or the exact annotation needed for a code block. This cheatsheet serves as a quick lookup for anyone wanting to use or understand the existing setup.

Why MDX?

The decision to use MDX was driven by the need for more than just static text. I wanted the ability to intersperse technical documentation with interactive elements, live previews, and rich media without sacrificing the readability of standard Markdown. By merging these two worlds, we get a powerful system that feels native to both developers and writers.

Basic Markdown Syntax

MDX supports all standard Markdown features out of the box. You can use these to structure your thoughts quickly before adding more complex components.

Typography and Lists

You can create headers, lists, and basic text formatting with simple symbols:

• Bold text for emphasis
• Italic text for subtle highlights
• Inline code for variables or short snippets

Quoteblocks are also supported for highlighting important thoughts or advice:

Markdown is the foundation, but MDX is the architecture that lets us build something more interactive.

Managing Metadata with Frontmatter

Every MDX file in this project requires a YAML frontmatter block at the very top. This is used by the build system to generate page titles, descriptions, and thumbnails.

---
title: My Post Title
description: A brief summary of the content.
tags: ["example", "tag"]
published: true
date: 2025-07-16
---

This metadata is crucial for SEO and for the automatic generation of the blog index and navigation links.

Syntax Highlighting with Rehype Pretty Code

To make code blocks readable, I use a plugin called rehype-pretty-code. This tool handles syntax highlighting during the build process, which means the user does not have to download a large library just to see colorized text.

Highlighting Features

The plugin supports several powerful annotations that go beyond standard colorization:

1. Line Highlighting: Use // [!code highlight] to draw attention to specific lines.
2. Diff Indicators: Use // [!code ++] or // [!code --] to show code changes.
3. Word Highlighting: Use // [!code word:X] to highlight every instance of a specific word.

Example Code Block

import { useFloating } from "@floating-ui/react";
 
function MyComponent() {
  const { refs, floatingStyles } = useFloating(); 
 
  return (
    <>
      <div ref={refs.setReference} />
      <div ref={refs.setFloating} style={floatingStyles} />
    </>
  );
}

Custom Components

One of the main reasons for using MDX is the ability to embed React components directly into the content. This is useful for building reusable UI patterns for documentation.

Alert Components

You can use an Alert component to call out specific information:

<Alert type="info">This is an info alert with **markdown** inside!</Alert>

These components are great for notes, warnings, or callouts that need to stand out from the rest of the text.

Embedding Rich Media

Beyond simple text and code, MDX allows for the integration of third party content using iframes and custom widgets.

Music and Audio

You can embed music players from Spotify or Apple Music to add a soundtrack to your posts or to share specific tracks.

Spotify Track

Spotify Album

Video Content

YouTube videos can be embedded with a simple iframe. I recommend using an aspect ratio of sixteen by nine to ensure the video scales correctly on all screen sizes.

GitHub Widgets

You can showcase repositories and user activity using custom React components designed for GitHub integration.

Repository Widget

Activity Widget

Technical Integration with Velite

Under the hood, this project uses Velite to manage the collection of MDX files. Velite treats your content like a database, allowing us to query for posts, sort them by date, and automatically validate the frontmatter.

The Benefits of Velite

• Type Safety: Every post is validated against a schema.
• Performance: Content is processed and optimized at build time.
• Flexibility: It allows us to easily add new rehype or remark plugins to extend the capabilities of the MDX system.

Final Thoughts

This cheatsheet will evolve as the project grows. It is the first place you should check when you are unsure about how to implement a specific feature in your writing. By following these patterns, we ensure that the entire site remains consistent and performant.

Image by Camila Q. Franco