Blog

Cómo Usar Nextra Docs y Desplegarlo en Vercel: Guía Paso a Paso

Ashley Goolam

Ashley Goolam

12 June 2025

Cómo Usar Nextra Docs y Desplegarlo en Vercel: Guía Paso a Paso

Si quieres crear un sitio web de documentación elegante y moderno con facilidad, Nextra Docs es una de las mejores herramientas disponibles. Construido sobre Next.js, Nextra te permite escribir tu documentación en Markdown o MDX, personalizar el aspecto y la sensación, y desplegarlo sin esfuerzo, especialmente en Vercel. En este artículo, te guiaremos paso a paso sobre cómo configurar un sitio Nextra Docs desde cero y desplegarlo en Vercel de forma gratuita.

💡
¿Quieres una excelente herramienta de pruebas de API que genere hermosa documentación de API?

¿Quieres una plataforma integrada, todo en uno, para que tu equipo de desarrolladores trabaje junto con la máxima productividad?

Apidog cumple todas tus demandas, ¡y reemplaza a Postman a un precio mucho más asequible!
botón

¿Qué es Nextra Docs? Tu Mejor Amigo para Construir Docs

Nextra docs es un framework basado en Next.js que facilita enormemente la creación de sitios de documentación. Se centra en el contenido Markdown (o MDX) con un Tema de Docs preconstruido que incluye navegación, búsqueda y una tabla de contenido listos para usar. Aquí te explicamos por qué nextra docs es genial:

Los usuarios elogian a nextra docs por su "pulido sin configuración" y los despliegues en Vercel. ¿Listo para construir tu sitio? ¡Vamos a ello!

¿Por qué Usar Nextra Docs con Vercel?

Nextra docs es perfecto para desarrolladores, startups o proyectos de código abierto que necesitan documentación profesional rápidamente. Combinarlo con Vercel —el terreno natural de Next.js— significa:

Desplegué un sitio de prueba en Vercel, y estuvo en vivo en menos de 5 minutos, ¡suave como la seda!

Cómo Configurar Nextra Docs: Guía Paso a Paso

Vamos a crear un sitio nextra docs desde cero usando el enrutador de aplicaciones de Next.js. Sigue los pasos y tendrás un sitio local funcionando en unos ~20 minutos.

1. Crea un Nuevo Proyecto Next.js

npx create-next-app my-nextra-docs
next js project options
cd my-nextra-docs

2. Instala las Dependencias de Nextra Docs

Instala los paquetes principales para nextra docs:

npm install next react react-dom nextra nextra-theme-docs

3. Actualiza los Scripts de package.json

Asegúrate de que package.json incluya estos scripts (normalmente los añade create-next-app):

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
}

"dev": "next --turbopack"
package.json
npm run dev

Visita http://localhost:3000 para confirmar que la aplicación Next.js funciona.

next js home page

Feo:( Pero bueno, ¡funciona! Ahora intentemos arreglar esto.

4. Configura Nextra Docs

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.js'
})

export default withNextra({
  async redirects() {
    return [
      {
        source: '/',
        destination: '/resources',
        permanent: true
      }
    ]
  }
})

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.mjs", ".next/types/**/*.ts"]

5. Configura Componentes MDX

import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'

const themeComponents = getThemeComponents()

export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

6. Actualiza el Layout de la Aplicación

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. Añade Páginas de Documentación

home page 404 error message
/app/resources
  /page.mdx

Para propósitos de prueba, añadí:

# Resources

Resources related to various topics and fields.

## Learning
- [Build Your Own X](https://github.com/codecrafters-io/build-your-own-x): Master programming by recreating your favourite technologies from scratch.

## Useful Articles
- [CSR vs SSR vs SSG vs ISR: A Deep Dive for Modern Web Development](csr-vs-ssr-vs-ssg-vs-isr-a-deep-dive-for-modern-web-development-33kl#:~:text=Here's%20a%20quick%20summary%3A,as%20SPAs%2C%20CSR%20is%20perfect.)
- [The Art of Comand Line](https://github.co./jlevy/the-art-of-command-line)

Pero el contenido no necesita ser complejo y puede ser tan simple como:

# Getting Started

Hi <Your Name>! Welcome to your **nextra docs** site:)

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in
nextra home page

Adelante, edita esta página, añade más páginas y prueba todas las funciones como el modo oscuro/claro. ¡El poder está en tus manos y las opciones son infinitas!

light and dark mode

Desplegando Nextra Docs en Vercel

Ahora, pongamos tu sitio nextra docs en vivo en Vercel—super fácil ya que Vercel está construido para Next.js.

8. Sube Tu Código a GitHub

git init
git add .
git commit -m "Initial nextra docs"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

9. Despliega en Vercel

varcel

Personalizando Tu Sitio Nextra Docs

¿Quieres que tu sitio nextra docs destaque? Prueba esto:

Añadí un componente de llamada personalizado a mis documentos, ¡se veía profesional en 10 minutos!

Solución de Problemas y Consejos para Nextra Docs

custom nextra documentation example

Por Qué Nextra Docs y Vercel Son la Pareja Perfecta

Nextra docs hace que la documentación sea divertida con su simplicidad Markdown y la velocidad de Next.js. Los despliegues con un solo clic y el alojamiento gratuito de Vercel cierran el trato. Claro, el enrutador de aplicaciones podría confundir a los novatos de Next.js, pero la documentación de Nextra es sólida. Comparado con Docusaurus, nextra docs se siente más ligero y moderno.

¿Listo para lanzar tus documentos? Construye tu sitio nextra docs y despliégalo en Vercel. ¡Estoy ansioso por ver tu creación! Y definitivamente, echa un vistazo a Apidog.

💡
¿Quieres una excelente herramienta de pruebas de API que genere hermosa documentación de API?

¿Quieres una plataforma integrada, todo en uno, para que tu equipo de desarrolladores trabaje junto con la máxima productividad?

Apidog cumple todas tus demandas, ¡y reemplaza a Postman a un precio mucho más asequible!
botón

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar