MD and MDX

CodeAltas supports writing documentation using Markdown (.md) and MDX (.mdx).

Markdown offers a simple, readable way to create structured content, while MDX builds upon Markdown by adding component capabilities, allowing documents to include interactive elements. Essentially, MDX is a combination of Markdown and JSX.

What is Markdown?

Markdown (often abbreviated as MD) is a lightweight markup language.

It uses simple symbols to represent text structures—such as headings, lists, links, and code blocks—enabling authors to focus on the content itself rather than writing raw HTML.

A simple Markdown file:

# Hello Code Altas

This is a paragraph.

- Item A
- Item B

1. List A
2. List B

... other

Key features of Markdown:

• Simple syntax
• Plain-text file format
• Easy version control
• Suitable for writing documentation, READMEs, blog posts, and more

What is MDX?

MDX stands for Markdown + JSX. It extends Markdown with JSX capabilities, allowing React components to be used directly within Markdown files.

Standard Markdown can only describe content:

# Installation

Install CodeAltas with npm.

MDX, however, allows for embedded components:

# Installation

<Steps>
  <Step label="Install">Add Code Atlas to your project.</Step>
</Steps>

Steps and Step are registered built-in JSX components.

Differences between Markdown and MDX

Although MDX incorporates Markdown, the two are not identical.

Code Atlas rendering rules

The table describes content rendered by Code Atlas. Its server renderer disables MDX import and export statements. Import custom React components in your Next.js page and pass them through DocsPage's components prop instead:

import { DocsPage, type DocsPageProps } from "@code-altas/ui"
import { InstallCommand } from "../../../components/install-command"

export const dynamic = "force-dynamic"

export default function Page({ params }: DocsPageProps) {
  return <DocsPage params={params} components={{ InstallCommand }} />
}

The example assumes your project provides components/install-command.tsx exporting InstallCommand. Once registered, use <InstallCommand /> in an .mdx article without importing it there. Client components must declare "use client" in their own module; keep the route page as a Server Component.

Markdown rendering supports tables, task lists, and strikethrough through GitHub Flavored Markdown. Raw HTML in .md is not enabled by the current renderer; use JSX in .mdx for HTML-like elements. MDX expressions such as {1 + 1} are supported, so keep document source under your project's control.

Use ## and ### for article sections: the page already renders the frontmatter title as its main heading. Store images in public, and use paths such as ![Screenshot](/images/screenshot.png). Links such as [Quick Start](/docs/quickstart) target configured documents; see File System for path mapping and Code Blocks for code examples.