Menu

Markdown & MDX

Here’s a well-crafted Markdown & MDX section to go along with your existing Docsta documentation topics:

Docsta supports both Markdown and MDX, allowing you to write rich, interactive documentation using simple syntax or embedded React components—all within the same file.

Whether you're documenting a library, API, or product feature, Markdown and MDX make writing fast, clean, and expressive.

1. Markdown Support

You can write your content using standard Markdown syntax:

# Getting Started
Welcome to the docs!
## Installation
Run the following command:
```bash
npx create-docsta

Markdown files are parsed and rendered using modern tools like `remark`, `rehype`, or your MDX bundler, depending on your setup.
---
### 2. What is MDX?
**MDX** extends Markdown with JSX support, which means you can import and use React components inside your docs—perfect for embedding custom UI elements like alerts, buttons, or live code blocks.
```mdx
import CustomAlert from '@/components/CustomAlert'
# Welcome
Here’s a custom callout:
<CustomAlert type="warning">
Make sure to install all dependencies before proceeding.
</CustomAlert>

This gives your documentation the power of Markdown with the flexibility of a React app.

2. MDX File Structure

MDX files are typically stored in a dedicated content folder:

content/
└── docs/
├── introduction.mdx
├── installation.mdx
└── configuration.mdx

These files are then fetched and rendered in your dynamic route handler using a loader like:

import { getMdxContent } from '@/lib/mdx'
3. Rendering MDX

Docsta uses next-mdx-remote or @next/mdx under the hood to compile and render MDX content in Next.js:

import { MDXRemote } from 'next-mdx-remote'
<MDXRemote {...mdxSource} components={customComponents} />

You can pass custom components (like callouts, tables, or code blocks) through a components prop to replace or enhance default HTML tags.

4. Frontmatter Support

Each MDX file can include frontmatter for metadata like title, description, and slug:

---
title: "Installation"
description: "How to install Docsta in your Next.js project"
slug: "installation"
---

This metadata can be used to build your sidebar navigation and SEO metadata.

5. MDX + Layouts

You can define a layout wrapper per page using MDX:

import Layout from '@/components/Layout'
<Layout>
## My Custom Page
</Layout>

Or wrap it globally using your page component or MDX renderer logic.

With Markdown and MDX, Docsta gives you the best of both worlds—easy authoring and advanced interactivity.

👉 Next Up: Learn how to fetch and manage content dynamically from Sanity Studio.

What did you think of this content?

like-icon

It was helpful

dislike-icon

It was not helpful

feedback-icon

I have a feedback