Saltar al contenido principal

Desplegar Tu Documentación

Esta guía explica cómo publicar este sitio de documentación en tu propio dominio personalizado — por ejemplo docs.tudominio.com.

Antes de Desplegar​

Primero, actualiza la URL del sitio en el archivo de configuración. Abre apps/docs/docusaurus.config.ts y cambia:

url: 'https://docs.tudominio.com',

Reemplaza tudominio.com con tu nombre de dominio real.

Opción 1 — Desplegar con Vercel (Recomendado)​

Vercel es la forma más sencilla de desplegar y mantener la documentación actualizada automáticamente. Es gratuito para la mayoría de los casos de uso y se vuelve a desplegar automáticamente cada vez que envías una actualización.

Pasos​

1. Sube el código a GitHub Asegúrate de que tu repositorio (o monorepo) esté subido a una cuenta de GitHub.

2. Conectar a Vercel

  • Ve a vercel.com e inicia sesión con tu cuenta de GitHub
  • Haz clic en Agregar Nuevo Proyecto y selecciona tu repositorio

3. Configurar los ajustes del proyecto

  • Establece el Directorio Raíz como apps/docs
  • Vercel detecta automáticamente Docusaurus y configura los ajustes de compilación correctos

4. Agregar tu dominio personalizado

  • En tu proyecto de Vercel, ve a Configuración → Dominios
  • Haz clic en Agregar Dominio e ingresa docs.tudominio.com
  • Vercel te proporcionará los registros DNS que necesitas agregar

5. Actualizar tu DNS

  • Inicia sesión en tu registrador de dominio (por ejemplo, GoDaddy, Namecheap, Cloudflare)
  • Agrega un registro CNAME:
    • Nombre / Host: docs
    • Valor / Apunta a: cname.vercel-dns.com
  • Los cambios de DNS generalmente surten efecto en pocos minutos a pocas horas

Una vez configurado, cada vez que envíes archivos de documentación actualizados, Vercel reconstruye y vuelve a publicar el sitio automáticamente.

Opción 2 — Alojamiento Propio con nginx​

Si prefieres alojar en tu propio servidor (VPS o servidor dedicado), sigue estos pasos.

Paso 1 — Compilar el Sitio​

En tu máquina local o pipeline de CI/CD:

cd apps/docs
pnpm install
pnpm run build

Esto genera una carpeta build/ que contiene el sitio estático completo (HTML, CSS y JavaScript).

Paso 2 — Subir a Tu Servidor​

Copia el contenido de la carpeta build/ a tu servidor. Usando rsync:

rsync -avz apps/docs/build/ usuario@tuservidor.com:/var/www/docs/

Paso 3 — Configurar nginx​

Crea un nuevo archivo de configuración de nginx en /etc/nginx/sites-available/docs:

server {
    listen 80;
    server_name docs.tudominio.com;

    root /var/www/docs;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Activa el sitio:

sudo ln -s /etc/nginx/sites-available/docs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Paso 4 — Activar HTTPS​

Usa Certbot para un certificado SSL gratuito:

sudo certbot --nginx -d docs.tudominio.com

Paso 5 — Configurar Tu DNS​

Agrega un registro DNS en tu registrador de dominio:

  • Tipo: A
  • Nombre / Host: docs
  • Valor: La dirección IP pública de tu servidor

Opción 3 — Desplegar con Netlify​

Netlify funciona de manera muy similar a Vercel:

  1. Conecta tu repositorio de GitHub en netlify.com
  2. Establece el Directorio base como apps/docs
  3. Establece el Comando de compilación como pnpm run build
  4. Establece el Directorio de publicación como apps/docs/build
  5. Agrega tu dominio personalizado en la configuración de dominios de Netlify

Proteger la Documentación Interna de Desarrolladores​

Docusaurus no incluye autenticación integrada, por lo que no es posible proteger con contraseña una sección del sitio de forma nativa. Para documentación interna de desarrolladores que requiera control de acceso, recomendamos uno de estos enfoques:

Cloudflare Access (Gratuito — Recomendado)​

Si tu dominio usa DNS de Cloudflare, puedes usar Cloudflare Access para restringir rutas URL específicas (por ejemplo, /dev/*) solo a direcciones de correo electrónico autorizadas. Es gratuito para hasta 50 usuarios y no requiere cambios en el código de la documentación.

Autenticación Básica de nginx (Alojamiento Propio)​

Si usas la opción de nginx, agrega Autenticación Básica HTTP a una ruta específica:

location /dev {
    auth_basic "Acceso de Desarrolladores";
    auth_basic_user_file /etc/nginx/.htpasswd;
    try_files $uri $uri/ /index.html;
}

Genera el archivo de contraseñas con:

sudo htpasswd -c /etc/nginx/.htpasswd devusuario

Despliegue Separado​

Mantén la documentación interna de desarrolladores en un repositorio o despliegue completamente separado, accesible solo desde direcciones IP específicas o mediante una URL privada.

Ejecutar la Documentación Localmente​

Para previsualizar la documentación en tu propia computadora:

cd apps/docs
pnpm install
pnpm run start

Abre http://localhost:3000 en tu navegador.

Para previsualizar la versión en español:

pnpm run start -- --locale es

Actualizar la Documentación​

Para actualizar cualquier página:

  1. Edita el archivo Markdown relevante en apps/docs/docs/ (inglés) o apps/docs/i18n/es/ (español)
  2. Previsualiza localmente con pnpm run start
  3. Sube tus cambios — el sitio se vuelve a desplegar automáticamente si usas Vercel o Netlify