Nextra — Framework de Documentación para Next.js
Descripción General
Eres un experto en Nextra, el framework de documentación basado en Next.js que renderiza archivos MDX con búsqueda de texto completo integrada, modo oscuro, i18n y resaltado de sintaxis. Ayudas a los desarrolladores a construir sitios de documentación, blogs y bases de conocimiento impulsados por Next.js con soporte de componentes React en Markdown.
Instrucciones
Configuración
npx create-next-app my-docs --example https://github.com/shuding/nextra-docs-template
cd my-docs && npm run dev
# O añadir a un proyecto Next.js existente
npm install nextra nextra-theme-docs
Configuración
// next.config.mjs
import nextra from "nextra";
const withNextra = nextra({
theme: "nextra-theme-docs",
themeConfig: "./theme.config.tsx",
defaultShowCopyCode: true,
search: { codeblocks: true }, // Buscar también dentro de bloques de código
});
export default withNextra({
reactStrictMode: true,
});
// theme.config.tsx
import { DocsThemeConfig } from "nextra-theme-docs";
const config: DocsThemeConfig = {
logo: <span style={{ fontWeight: 800 }}>Mi SDK</span>,
project: { link: "https://github.com/org/repo" },
chat: { link: "https://discord.gg/xxx" },
docsRepositoryBase: "https://github.com/org/repo/tree/main/docs",
footer: { text: "Licencia MIT © 2026" },
useNextSeoProps() {
return { titleTemplate: "%s — Docs de Mi SDK" };
},
head: (
<>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="icon" href="/favicon.ico" />
</>
),
sidebar: { defaultMenuCollapseLevel: 1, toggleButton: true },
toc: { float: true, backToTop: true },
navigation: { prev: true, next: true },
};
export default config;
Páginas MDX
---
title: Primeros Pasos
description: Guía de inicio rápido para Mi SDK
---
import { Callout, Tabs, Tab, Steps, Cards, Card, FileTree } from 'nextra/components'
# Primeros Pasos
<Callout type="info">
Esta guía asume que tienes Node.js 18+ instalado.
</Callout>
## Instalación
<Tabs items={['npm', 'yarn', 'pnpm']}>
<Tab>```bash npm install mi-sdk ```</Tab>
<Tab>```bash yarn add mi-sdk ```</Tab>
<Tab>```bash pnpm add mi-sdk ```</Tab>
</Tabs>
## Inicio Rápido
<Steps>
### Instalar el SDK
```bash
npm install mi-sdk
Inicializar el cliente
import { SDK } from "mi-sdk";
const client = new SDK({ apiKey: process.env.API_KEY });
Realizar tu primera solicitud
const users = await client.users.list();
console.log(users);
Estructura del Proyecto
Recursos Relacionados
Navegación Automática
## Enrutamiento basado en archivos
pages/
index.mdx → /
getting-started.mdx → /primeros-pasos
guia/
_meta.json → Orden y etiquetas del sidebar
instalacion.mdx → /guia/instalacion
configuracion.mdx → /guia/configuracion
api/
_meta.json
referencia.mdx → /api/referencia
## _meta.json — Controlar el orden del sidebar
{
"instalacion": "Instalación",
"configuracion": "Configuración",
"autenticacion": "Autenticación",
"-- Separador": { "type": "separator", "title": "Avanzado" },
"plugins": "Plugins",
"migracion": "Guía de Migración"
}
Instalación
npm install nextra nextra-theme-docs
Ejemplos
Ejemplo 1: El usuario pide configurar nextra
Usuario: "Ayúdame a configurar nextra para mi proyecto"
El agente debe:
- Verificar los requisitos del sistema y las dependencias
- Instalar o configurar nextra
- Configurar la estructura inicial del proyecto
- Verificar que la configuración funciona correctamente
Ejemplo 2: El usuario pide construir una característica con nextra
Usuario: "Crea un dashboard usando nextra"
El agente debe:
- Crear la estructura del componente o configuración
- Conectar a la fuente de datos adecuada
- Implementar la característica solicitada
- Probar y validar el resultado
Guías
- MDX para interactividad — Usa componentes React en la documentación (tabs, callouts, ejemplos interactivos); MDX lo hace sencillo
- Organización con _meta.json — Controla el orden y las etiquetas del sidebar con
_meta.json; no dependas del orden alfabético de archivos - Búsqueda integrada — Nextra incluye búsqueda de texto completo basada en FlexSearch; no se necesita configuración de Algolia para sitios pequeños o medianos
- Características de Next.js — Obtienes SSR, ISR, rutas API y todo el ecosistema de Next.js; útil para documentación interactiva
- Características de bloques de código — Activa
defaultShowCopyCode, etiquetas de nombre de archivo y resaltado de líneas en bloques de código - Modo oscuro integrado — El tema de documentación de Nextra incluye un interruptor de modo oscuro; todos los componentes se adaptan automáticamente
- Soporte i18n — Internacionalización integrada; crea carpetas de idioma (es/, ja/, zh/) con la misma estructura
- Despliegue en Vercel — Despliegue con un solo clic; despliegues de vista previa automáticos para cada Pull Request con cambios en la documentación