ServBay

Español

English
简体中文
繁體中文
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย
한국어

Español

English
简体中文
繁體中文
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย
한국어

Appearance

Crear y ejecutar un proyecto VitePress con ServBay ​

VitePress es un generador moderno de sitios estáticos, impulsado por Vue y especialmente diseñado para crear sitios de documentación rápidos, atractivos y fáciles de mantener. Basado en Vite, ofrece una experiencia de desarrollo y rendimiento de construcción excepcionales. Es una elección ideal para desarrolladores que necesitan documentación profesional para proyectos, bibliotecas o productos.

Durante el desarrollo y las pruebas locales de VitePress, es esencial contar con un entorno de desarrollo web estable y fácil de configurar. ServBay responde a esta necesidad al integrar varias versiones de Node.js y potentes servidores web (como Caddy o Nginx) que permiten servir tus proyectos VitePress sin complicaciones.

En este artículo te guiaremos para crear, configurar y ejecutar un proyecto VitePress desde cero aprovechando el entorno integrado de ServBay, incluyendo la configuración de proxy inverso para el servidor de desarrollo y el servicio de archivos estáticos para la versión de producción.

¿Qué es VitePress? ​

VitePress es un generador de sitios estáticos (SSG) basado en Vite, que utiliza la potencia de Vue 3 y el alto rendimiento de Vite para construir sitios estáticos, siendo especialmente adecuado para documentación técnica.

Principales características y ventajas de VitePress ​

  • Desarrollo ultrarrápido: Gracias al reemplazo en caliente de módulos (HMR) de Vite, los cambios se ven reflejados al instante en el navegador, aumentando la eficiencia en el desarrollo.
  • Impulsado por Vue: Permite usar componentes Vue directamente en archivos Markdown, enriqueciendo la interactividad y expresión de tu documentación.
  • Sencillo y fácil de utilizar: Configuración mínima y preparado para empezar; enfócate en crear contenido.
  • Alto rendimiento: Los archivos estáticos generados son pequeños y se cargan rápido; la experiencia se asemeja a una SPA gracias al enrutamiento integrado.
  • Optimizado para SEO: Estructura HTML que facilita el rastreo de buscadores y soporte para etiquetas personalizadas en el <head>.
  • Markdown Mejorado: Soporta todas las funciones de CommonMark y GitHub Flavored Markdown (GFM), junto con azúcares sintácticos adicionales.

Con VitePress, los desarrolladores pueden crear fácilmente sitios de documentación de alta calidad y gran rendimiento.

Crear y ejecutar un proyecto VitePress con ServBay ​

ServBay facilita la gestión de diversas versiones de Node.js y la configuración de servidores web para tu proyecto VitePress, tanto en modo de desarrollo como en producción.

Requisitos previos ​

Antes de comenzar, asegúrate de cumplir con los siguientes requisitos:

  1. Instalar ServBay: Ya debes tener ServBay instalado correctamente en tu sistema macOS. Si aún no lo has hecho, consulta la Guía de instalación de ServBay.
  2. Instalar el paquete Node.js: En ServBay, verifica que tienes instalada y habilitada la versión necesaria de Node.js. Puedes administrarlo desde la pestaña “Paquetes” del panel de ServBay. Consulta más detalles en Uso de Node.js.

Crear un nuevo proyecto VitePress ​

  1. Inicializar el directorio del proyecto

    Abre tu terminal y ubica la carpeta raíz de sitios de ServBay, /Applications/ServBay/www, para crear una nueva carpeta de proyecto, lo que facilitará la configuración posterior en ServBay.

    bash
    cd /Applications/ServBay/www
mkdir servbay-vitepress-app
cd servbay-vitepress-app

  2. Instalar VitePress e iniciar configuración

    Dentro de servbay-vitepress-app, instala VitePress como dependencia de desarrollo y ejecuta el comando de inicialización con npm o yarn.

    bash
    npm add -D vitepress
npx vitepress init

    o usando Yarn:

    bash
    yarn add -D vitepress
yarn vitepress init

    El comando de inicialización te guiará por configuraciones básicas, como el título y la descripción del sitio. Proporciona la información que se te solicita:

     ┌  ¡Bienvenido a VitePress!
 │
 ◇  ¿Dónde debes inicializar la configuración de VitePress?
 │  ./docs  # Directorio predeterminado para archivos, pulsa ENTER para confirmar
 │
 ◇  Título del sitio:
 │  ServBay VitePress Demo # Escribe el título de tu sitio, por ejemplo ServBay VitePress Demo
 │
 ◇  Descripción del sitio:
 │  Un sitio VitePress corriendo en ServBay # Escribe la descripción de tu sitio
 │
 ◇  Tema:
 │  Default Theme # Elije el tema, el predeterminado está bien
 │
 ◇  ¿Usar TypeScript para la configuración y archivos de tema?
 │  Yes # Según tu preferencia, selecciona Yes para TypeScript
 │
 ◇  ¿Agregar scripts de npm de VitePress en package.json?
 │  Yes # Recomendado seleccionar Yes para facilitar scripts
 │
 └  ¡Listo! Ahora corre npm run docs:dev y empieza a escribir.

    Tras finalizar, se creará un subdirectorio docs dentro del proyecto, con archivos de configuración predeterminados (.vitepress) y páginas de ejemplo (index.md, guide/index.md, etc.). También se actualizará package.json con los scripts docs:dev y docs:build.

Modificar el contenido de tu proyecto VitePress ​

  1. Editar la página principal

    El archivo de la página principal de VitePress por defecto es docs/index.md. Ábrelo con tu editor de texto favorito y modifica el contenido, por ejemplo:

    markdown
    # ¡Hola ServBay!

Bienvenido a usar ServBay para ejecutar tu sitio de documentación con VitePress.

Este es un sitio de demostración local creado con VitePress y servido con ServBay.

Entrar en modo desarrollo ​

Es común usar el servidor integrado de desarrollo de VitePress durante la creación, ya que permite previsualización en tiempo real con recarga instantánea. Aprovecha la función de proxy inverso de ServBay para acceder al servidor de desarrollo usando un dominio personalizado con cifrado SSL.

  1. Ejecutar el servidor de desarrollo de VitePress

    En la terminal y dentro del directorio /Applications/ServBay/www/servbay-vitepress-app, inicia el servidor de desarrollo indicando un puerto, por ejemplo 8585:

    bash
    npm run docs:dev -- --port 8585

    o, si usas Yarn:

    bash
    yarn docs:dev --port 8585

    El servidor escuchará en el puerto especificado (p.ej. 8585). En la terminal se mostrará la dirección local, usualmente http://localhost:8585.

  2. Configurar el sitio en ServBay (proxy inverso)

    Accede al panel de ServBay y entra en “Sitios”. Haz clic en “Añadir una nueva configuración de sitio”.

    • Nombre: Elige un nombre fácil de identificar, como Sitio VitePress Desarrollo.
    • Dominio: Elige el dominio local que usarás para el desarrollo. Se recomienda el sufijo .servbay.demo, por ejemplo vitepress-dev.servbay.demo.
    • Tipo de sitio: Selecciona Proxy inverso.
    • IP: Introduce 127.0.0.1 (localhost).
    • Puerto: Introduce el puerto que especificaste antes, por ejemplo 8585.

    Guarda y aplica los cambios. ServBay configurará automáticamente el servidor web (Caddy o Nginx) para redirigir las solicitudes de https://vitepress-dev.servbay.demo a http://127.0.0.1:8585.

  3. Acceder al sitio de desarrollo

    Ahora puedes acceder a https://vitepress-dev.servbay.demo en tu navegador. Verás el contenido servido por el servidor de desarrollo de VitePress. Además de usar un dominio personalizado, tienes habilitado HTTPS mediante un certificado SSL generado por ServBay User CA.

Generar la versión de producción ​

Cuando tu documentación esté lista para publicarse, procede a compilar una versión optimizada y estática.

  1. Construir la versión de producción

    Desde /Applications/ServBay/www/servbay-vitepress-app, ejecuta:

    bash
    npm run docs:build

    o con Yarn:

    bash
    yarn docs:build

    Esto compilará todos tus archivos Markdown, componentes Vue, etc., generando archivos HTML, CSS y JS optimizados en el directorio docs/.vitepress/dist del proyecto.

  2. Configurar el sitio ServBay (servicio de archivos estáticos)

    Dado que el sitio VitePress de producción es un conjunto de archivos estáticos, usa la función de “Sitio estático” de ServBay para servirlos.

    Desde el panel de ServBay, ve a la sección “Sitios” y añade una nueva configuración.

    • Nombre: Por ejemplo, Sitio VitePress Producción.
    • Dominio: Elige un dominio local para tu entorno de producción, como vitepress-prod.servbay.demo.
    • Tipo de sitio: Escoge Estático.
    • Directorio raíz: Introduce la ruta absoluta de tu carpeta de archivos generados: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

    Guarda y aplica los cambios. ServBay servirá los archivos estáticos directamente desde el directorio especificado.

  3. Acceder al sitio de producción

    Accede al dominio configurado https://vitepress-prod.servbay.demo para ver tu sitio de producción construido con VitePress, también disponible con dominio personalizado y cifrado SSL automático.

Funcionamiento con URLs limpias (cleanUrls: true) ​

VitePress puede configurarse con cleanUrls: true, generando enlaces sin la extensión .html (por ejemplo, /guide/ en lugar de /guide/index.html, o /about en lugar de /about.html). Esto requiere ajustar la configuración del servidor para manejar correctamente esas rutas.

ServBay usa Caddy o Nginx como servidor web. Aquí tienes un ejemplo de configuración para Caddy, usando la directiva try_files para buscar archivos con y sin extensión o dentro de carpetas:

  1. Habilita cleanUrls en la configuración de VitePress

    Edita el archivo de configuración de VitePress (docs/.vitepress/config.mts o docs/.vitepress/config.ts) y agrega o modifica la opción cleanUrls en siteConfig:

    typescript
    // docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ... otras configuraciones
  cleanUrls: true, // Activar URLs limpias
  // ... otras configuraciones
})

    Vuelve a ejecutar npm run docs:build para reconstruir la versión de producción.

  2. Configura el sitio en ServBay (usando configuración personalizada de Caddy)

    En el panel de ServBay, ve al sitio que corresponde al entorno de producción (por ejemplo, vitepress-prod.servbay.demo).

    • Haz clic en editar.
    • Marca la opción Configuración personalizada.
    • En el área de texto de Configuración Caddy, pega la siguiente configuración. Cambia servbay-vitepress-test.prod por tu dominio real y la ruta /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist por la de tu instancia.
    bash
    # Cambia por tu dominio real, por ejemplo vitepress-cleanurl.servbay.demo
vitepress-cleanurl.servbay.demo {
    # Habilita Brotli (zstd) y compresión Gzip para mejorar la velocidad
    encode zstd gzip

    # Importa la configuración de logs predeterminada de ServBay para depuración
    import set-log vitepress-cleanurl.servbay.demo

    # Certificado SSL generado internamente por ServBay
    tls internal

    # Configuración clave: búsqueda de archivos
    # 1. Busca la ruta exacta (por ejemplo, /about -> /about)
    # 2. Busca un index.html dentro del directorio (por ejemplo, /guide/ -> /guide/index.html)
    # 3. Busca el archivo agregando .html (por ejemplo, /about -> /about.html)
    try_files {path} {path}/index.html {path}.html

    # Directorio raíz del sitio
    root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

    # Servicio de archivos estáticos
    file_server
}

    Guarda y aplica los cambios.

  3. Acceder al sitio con URLs limpias

    Ingresa al dominio configurado (por ejemplo, https://vitepress-cleanurl.servbay.demo). Ahora puedes acceder a páginas como about.html simplemente visitando https://vitepress-cleanurl.servbay.demo/about, sin incluir la extensión .html.

Resumen ​

Siguiendo esta guía, ahora sabes cómo crear, desarrollar y desplegar un sitio de documentación VitePress usando ServBay. ServBay simplifica la gestión de entornos Node.js y la configuración de servidores web locales, tanto en desarrollo (con el proxy inverso) como en producción (con servicio de archivos estáticos), brindando además soporte automático para dominios personalizados y certificados SSL.

Aprovecha la potente combinación de ServBay y VitePress para crear y mantener de forma más eficiente documentación técnica de alta calidad.