Sitio de documentación Next.js + MDX

Crea un sitio de documentación con Next.js 15, MDX y Tailwind — la arquitectura detrás de este cookbook.

Receta

1. Scaffold Next.js con Tailwind y TypeScript:

   npx create-next-app@latest docs-site --typescript --tailwind --app
   cd docs-site

2. Instala herramientas MDX:

   npm install next-mdx-remote gray-matter

3. Crea un directorio docs/ en la raíz del proyecto para archivos .md, organizados como docs/<section>/<slug>.md.
4. Crea rutas dinámicas en app/docs/[section]/[slug]/page.tsx.
5. Lee archivos con fs, analiza el frontmatter con gray-matter, renderiza con <MDXRemote> de next-mdx-remote/rsc.
6. Usa generateStaticParams para prerrenderizar todos los documentos en tiempo de compilación.

Ejemplo funcional

lib/docs.ts

import fs from "node:fs/promises";
import path from "node:path";
import matter from "gray-matter";
 
const DOCS_DIR = path.join(process.cwd(), "docs");
 
export interface DocFrontmatter \{
  title: string;
  section: string;
  order: number;
  tags?: string[];
\}
 
export interface Doc \{
  section: string;
  slug: string;
  frontmatter: DocFrontmatter;
  content: string;
\}
 
export async function getAllDocs(): Promise<Doc[]> \{
  const sections = await fs.readdir(DOCS_DIR, \{ withFileTypes: true \});
  const docs: Doc[] = [];
 
  for (const section of sections) \{
    if (!section.isDirectory()) continue;
    const files = await fs.readdir(path.join(DOCS_DIR, section.name));
 
    for (const file of files) \{
      if (!file.endsWith(".md")) continue;
      const raw = await fs.readFile(
        path.join(DOCS_DIR, section.name, file),
        "utf8"
      );
      const \{ data, content \} = matter(raw);
      docs.push(\{
        section: section.name,
        slug: file.replace(/\.md$/, ""),
        frontmatter: data as DocFrontmatter,
        content,
      \});
    \}
  \}
 
  return docs.sort((a, b) => a.frontmatter.order - b.frontmatter.order);
\}
 
export async function getDoc(section: string, slug: string): Promise<Doc | null> \{
  try \{
    const raw = await fs.readFile(
      path.join(DOCS_DIR, section, `$\{slug\}.md`),
      "utf8"
    );
    const \{ data, content \} = matter(raw);
    return \{
      section,
      slug,
      frontmatter: data as DocFrontmatter,
      content,
    \};
  \} catch \{
    return null;
  \}
\}

app/docs/[section]/[slug]/page.tsx

import \{ notFound \} from "next/navigation";
import \{ MDXRemote \} from "next-mdx-remote/rsc";
import \{ getAllDocs, getDoc \} from "@/lib/docs";
 
export async function generateStaticParams() \{
  const docs = await getAllDocs();
  return docs.map((doc) => (\{
    section: doc.section,
    slug: doc.slug,
  \}));
\}
 
interface PageProps \{
  params: Promise<\{ section: string; slug: string \}>;
\}
 
export default async function DocPage(\{ params \}: PageProps) \{
  const \{ section, slug \} = await params;
  const doc = await getDoc(section, slug);
  if (!doc) notFound();
 
  return (
    <article className="prose prose-slate mx-auto max-w-3xl py-12">
      <h1>\{doc.frontmatter.title\}</h1>
      <MDXRemote source=\{doc.content\} />
    </article>
  );
\}

Componentes MDX personalizados (opcional)

// components/mdx-components.tsx
import type \{ MDXComponents \} from "mdx/types";
 
export const mdxComponents: MDXComponents = \{
  h2: (props) => <h2 className="mt-8 text-2xl font-bold" \{...props\} />,
  code: (props) => (
    <code className="rounded bg-slate-100 px-1 py-0.5 text-sm" \{...props\} />
  ),
\};

Pásalos a <MDXRemote source=\{content\} components=\{mdxComponents\} />.

Análisis profundo

Cómo funciona

next-mdx-remote/rsc es un componente async React Server que compila MDX en el servidor y transmite el resultado. No hay tiempo de ejecución MDX del lado del cliente, no hay paso de bundler para tu contenido y no hay pipeline de compilación separada. En tiempo de compilación, generateStaticParams produce cada par (section, slug) para que Next.js prerrenderice estáticamente cada página de documento en HTML.

gray-matter divide cada archivo .md en un objeto de frontmatter y una cadena de contenido. La cadena de contenido se pasa verbatim a MDXRemote, que maneja el análisis, la transformación (a través de plugins remark/rehype) y el renderizado.

Variaciones

• Resaltado de sintaxis: añade rehype-pretty-code y Shiki para resaltado de calidad de VS Code en tiempo de compilación:

  <MDXRemote
    source=\{content\}
    options=\{\{ mdxOptions: \{ rehypePlugins: [[rehypePrettyCode, \{ theme: "github-dark" \}]] \} \}\}
  />

• Markdown con sabor GitHub: añade remark-gfm para tablas, listas de tareas y tachado.
• Componentes personalizados: mapea h1, h2, pre, a, img a componentes React estilizados para una prosa consistente.
• Barra lateral autogenerada: camina por el directorio docs/ en tiempo de compilación con getAllDocs(), agrupa por sección y renderiza un componente de navegación.
• Búsqueda: precomputa un índice Fuse.js en tiempo de compilación y envíalo como un archivo JSON que el cliente carga bajo demanda.
• Tabla de contenidos: extrae encabezados con rehype-slug y remark-extract-toc, renderiza una tabla de contenidos pegajosa en el diseño del artículo.

Notas de TypeScript

• Define una interfaz DocFrontmatter y lanza matter(raw).data as DocFrontmatter. Considera la validación de zod para fallar ruidosamente en el frontmatter malformado.
• En Next.js 15, params es una Promise — escríbela como params: Promise<\{ section: string; slug: string \}> y await antes de usarla.
• Para componentes MDX personalizados, importa el tipo MDXComponents de mdx/types.

Trampas

1. Las llaves son expresiones MDX. Escribir \{foo\} en prosa intentará evaluar foo como JavaScript y fallará en la compilación. Escapa con una barra invertida \\\{foo\\\}, envuelve en backticks o usa entidades HTML {.
2. Las etiquetas similares a JSX rompen MDX. Escribir <Component /> en prosa se analiza como JSX. Si el componente no está en scope, MDX lanza. Envuelve en backticks o escapa < como <.
3. Enlaces relativos de .md. Los enlaces de Markdown como [see](./other.md) no coinciden con tu estructura de rutas. Reescríbelos en tiempo de renderizado con un componente a personalizado o un plugin remark.
4. MDXRemote es async. Solo funciona en Server Components. Ponerlo en un Client Component lanza en tiempo de ejecución.
5. fs solo se ejecuta del lado del servidor. Importar lib/docs.ts desde un Client Component activa Module not found: node:fs. Mantenlo en RSC o manejadores de rutas.
6. Contenido obsoleto después de ediciones. Si usas export const dynamic = "force-static", los documentos recién añadidos requieren una reconstrucción. Usa revalidate o elimina la caché si quieres reconstrucciones bajo demanda.
7. Errores tipográficos en frontmatter fallan silenciosamente. gray-matter devuelve las claves que encuentra. Valida con zod o una aserción tipada para detectar los campos title u order faltantes temprano.

Alternativas

Preguntas frecuentes

<MDXRemote
  source=\{content\}
  options=\{\{
    mdxOptions: \{
      rehypePlugins: [[rehypePrettyCode, \{ theme: "github-dark" \}]],
    \},
  \}\}
/>

const a = (\{ href, ...rest \}: any) => \{
  const rewritten = href?.endsWith(".md")
    ? href.replace(/\.md$/, "")
    : href;
  return <a href=\{rewritten\} \{...rest\} />;
\};

interface DocFrontmatter \{ title: string; order: number \}
const \{ data \} = matter(raw);
const frontmatter = data as DocFrontmatter;

interface PageProps \{
  params: Promise<\{ section: string; slug: string \}>;
\}
 
export default async function Page(\{ params \}: PageProps) \{
  const \{ section, slug \} = await params;
\}

Relacionado

• Next.js Setup: Prisma + PostgreSQL
• Next.js Setup: Auth.js v5
• Next.js Routing: App Router
• React 19: Server Components