Crear y ejecutar un proyecto VitePress con ServBay

VitePress es un generador moderno de sitios web estáticos impulsado por Vue, diseñado específicamente para crear sitios de documentación rápidos, atractivos y fáciles de mantener. Basado en Vite, provee una excelente experiencia de desarrollo y un alto rendimiento de construcción. Para desarrolladores que necesitan documentación profesional para proyectos, bibliotecas o productos, VitePress es una opción ideal.

Al desarrollar y testear VitePress localmente, contar con un entorno web estable y fácil de configurar es fundamental. ServBay está hecho precisamente para esto: integra múltiples versiones de Node.js y potentes servidores web (como Caddy o Nginx), facilitando el despliegue de tus proyectos VitePress.

Esta guía te mostrará cómo aprovechar el entorno integrado de ServBay para crear, configurar y ejecutar tu proyecto VitePress desde cero, incluyendo el uso de proxy inverso durante el desarrollo y la configuración del servicio de archivos estáticos en producción.

¿Qué es VitePress?

VitePress es un generador de sitios web estáticos (SSG) basado en Vite, que utiliza la potencia de Vue 3 y el rendimiento ultra-rápido de Vite para crear sitios estáticos, especialmente optimizados para documentación técnica.

Principales características y ventajas de VitePress

Experiencia de desarrollo ultra-rápida: Gracias al reemplazo en caliente de módulos (HMR) de Vite, los cambios se reflejan casi al instante en el navegador, lo que eleva la eficiencia de desarrollo.
Impulsado por Vue: Permite usar componentes Vue directamente dentro de archivos Markdown, mejorando enormemente la interactividad y expresividad de la documentación.
Simplicidad y facilidad de uso: Configuración sencilla y lista para usar, centrada en la creación de contenido.
Alto rendimiento: Los archivos estáticos generados son livianos y cargan rápido; con enrutamiento de cliente incorporado se ofrece una experiencia fluida tipo SPA.
Amigable con SEO: La estructura HTML generada facilita el indexado por buscadores, además permite personalizar las etiquetas de cabecera.
Markdown mejorado: Soporta todas las funciones de CommonMark y GitHub Flavored Markdown (GFM), y agrega sintaxis adicional.

Con VitePress, los desarrolladores pueden crear sitios de documentación de alta calidad y rendimiento de manera sencilla.

Crear y ejecutar un proyecto VitePress con ServBay

ServBay facilita la gestión de versiones de Node.js y la configuración de servidores web para tus proyectos VitePress, tanto para servidores locales en desarrollo como para archivos estáticos en producción.

Requisitos previos

Antes de comenzar, asegúrate de cumplir lo siguiente:

Instalar ServBay: ServBay debe estar instalado correctamente en tu sistema. Si aún no lo has hecho, consulta la Guía de instalación de ServBay.
Instalar paquetes Node.js: Verifica que has instalado y activado la versión necesaria del paquete Node.js dentro de ServBay. Puedes gestionarlo desde la sección "Paquetes" del panel de control de ServBay. Consulta Uso de Node.js.

Crear el proyecto VitePress

Inicializar el directorio de tu proyecto
Abre tu terminal. Se recomienda crear la carpeta del proyecto dentro del directorio raíz predeterminado de ServBay para facilitar la futura configuración.
macOS:
bash
```
cd /Applications/ServBay/www
mkdir servbay-vitepress-app
cd servbay-vitepress-app
```
1
2
3
Windows:
cmd
```
cd C:\ServBay\www
mkdir servbay-vitepress-app
cd servbay-vitepress-app
```
1
2
3

Instalar VitePress e inicializar la configuración

Dentro del directorio servbay-vitepress-app, instala VitePress como dependencia de desarrollo y ejecuta el comando de inicialización.

bash

npm add -D vitepress
npx vitepress init

O con Yarn:

bash

yarn add -D vitepress
yarn vitepress init

El comando de inicialización te irá guiando por algunos ajustes básicos como el título y la descripción del sitio. Ingresa según se solicita:

 ┌  ¡Bienvenido a VitePress!
 │
 ◇  ¿Dónde debe VitePress inicializar la configuración?
 │  ./docs  # Directorio predeterminado para la documentación, presiona Enter para aceptar
 │
 ◇  Título del sitio:
 │  ServBay VitePress Demo # Introduce el título de tu sitio, por ejemplo ServBay VitePress Demo
 │
 ◇  Descripción del sitio:
 │  Un sitio VitePress ejecutándose en ServBay # Introduce la descripción del sitio
 │
 ◇  Tema:
 │  Tema predeterminado # Selecciona el tema, normalmente el predeterminado
 │
 ◇  ¿Usar TypeScript para los archivos de configuración y tema?
 │  Sí # Elige según tu preferencia
 │
 ◇  ¿Agregar scripts de VitePress npm a package.json?
 │  Sí # Recomendado seleccionar Sí
 │
 └  ¡Listo! Ahora ejecuta npm run docs:dev y comienza a escribir.

Tras finalizar, VitePress creará un subdirectorio docs dentro de servbay-vitepress-app, con archivos de configuración predeterminados (.vitepress) y páginas de ejemplo (index.md, guide/index.md, etc.). Además, se actualizará el package.json agregando los comandos docs:dev y docs:build.

Editar el contenido del proyecto VitePress

Modificar el contenido de la página principal
El archivo predeterminado de la página principal de VitePress es docs/index.md. Ábrelo con tu editor de texto preferido y modifica el contenido, por ejemplo:
markdown
```
# ¡Hola ServBay!

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

Este es un sitio de demostración local creado con VitePress y servido por ServBay.
```
1
2
3
4
5

Entrar en modo desarrollo

Durante el desarrollo del sitio VitePress, es común utilizar el servidor interno de desarrollo, el cual ofrece recarga en caliente para una previsualización instantánea. Mediante la funcionalidad de proxy inverso de ServBay, podrás acceder con un dominio personalizado, disfrutando también de conexión SSL automática.

Ejecutar el servidor de desarrollo de VitePress
Desde el directorio del proyecto (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), ejecuta el siguiente comando para iniciar el servidor e indicar el puerto (por ejemplo, 8585).
bash
```
npm run docs:dev -- --port 8585
```
1
O con Yarn:
bash
```
yarn docs:dev --port 8585
```
1
El servidor de desarrollo se iniciará y escuchará en el puerto elegido (por ejemplo, 8585). El terminal mostrará la URL, normalmente http://localhost:8585.
Configurar el sitio en ServBay (Proxy inverso)
Accede al panel de control de ServBay y entra en la sección "Sitios". Haz clic para añadir una nueva configuración de sitio.
- Nombre: Escribe un nombre identificativo, por ejemplo Sitio de desarrollo VitePress.
- Dominio: Escribe el dominio local que deseas utilizar. Por recomendaciones de ServBay y para evitar conflictos, utiliza el sufijo .servbay.demo, por ejemplo, vitepress-dev.servbay.demo.
- Tipo de sitio: Selecciona Proxy inverso.
- IP: Coloca 127.0.0.1 (localhost).
- Puerto: Coloca el puerto que elegiste en el paso anterior, por ejemplo 8585.
Guarda y aplica los cambios. ServBay configurará automáticamente el servidor web (Caddy o Nginx) para redirigir las solicitudes a https://vitepress-dev.servbay.demo hacia http://127.0.0.1:8585.
Acceder al sitio en desarrollo
Ahora puedes acceder en tu navegador al dominio configurado: https://vitepress-dev.servbay.demo. Deberías ver el sitio que sirve VitePress en modo desarrollo. Gracias a ServBay, dispones de dominio personalizado y certificado SSL emitido por ServBay User CA para navegación segura por HTTPS.

Construir la versión de producción

Cuando hayas terminado la documentación y quieras publicar tu sitio, es momento de generar la versión optimizada de archivos estáticos.

Crear la versión de producción
Desde el directorio del proyecto (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app), ejecuta:
bash
```
npm run docs:build
```
1
O con Yarn:
bash
```
yarn docs:build
```
1
El proceso compila tus archivos Markdown y componentes Vue en HTML, CSS y JavaScript estáticos optimizados. Los archivos generados se encuentran por defecto en docs/.vitepress/dist dentro de tu proyecto.
Configurar el sitio en ServBay (Servicio de archivos estáticos)
La versión de producción es un conjunto de archivos estáticos, así que puedes servirlos directamente con la función de archivos estáticos de ServBay.
En el panel de control, ve a "Sitios" y añade una nueva configuración.
- Nombre: Escribe un nombre reconocible, por ejemplo Sitio VitePress en producción.
- Dominio: Elige el dominio para la versión de producción, por ejemplo vitepress-prod.servbay.demo.
- Tipo de sitio: Elige Estático.
- Directorio raíz del sitio: Indica la ruta absoluta del directorio donde están los archivos generados:
  - macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
  - Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
Guarda y aplica los cambios. ServBay configurará el servidor web para servir los archivos directamente desde el directorio indicado.
Acceder al sitio en producción
Ahora visita el dominio configurado https://vitepress-prod.servbay.demo en tu navegador. Verás la versión de producción de tu sitio VitePress, con dominio personalizado y SSL gestionado automáticamente por ServBay.

Usar el modo de URLs limpias (`cleanUrls: true`)

VitePress soporta la opción cleanUrls: true, lo que significa que los enlaces de las páginas generadas no tendrán la extensión .html (por ejemplo, /guide/ en vez de /guide/index.html, o /about en vez de /about.html). Para que el servidor web maneje estos enlaces correctamente, se requiere configuración adicional.

ServBay utiliza Caddy o Nginx como servidores web. A continuación, un ejemplo para Caddy que usa la directiva try_files para buscar el archivo correspondiente (ya sea con extensión .html o como index.html en la carpeta).

Activar cleanUrls en la configuración de VitePress
Edita tu archivo de configuración de VitePress (docs/.vitepress/config.mts o docs/.vitepress/config.ts), y añade o modifica la opción cleanUrls dentro de siteConfig:
typescript
```
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // ... otras configuraciones
  cleanUrls: true, // Habilitar URLs limpias
  // ... otras configuraciones
})
```
1
2
3
4
5
6
7
8
Vuelve a ejecutar npm run docs:build para generar la versión de producción.

Configurar el sitio en ServBay (Caddy personalizado)

En el panel de control de ServBay, busca la configuración de tu sitio de producción VitePress (por ejemplo, vitepress-prod.servbay.demo).

Haz clic en editar.
Activa la opción Configuración personalizada.
Escribe o pega la siguiente configuración en el área de texto para Caddy, reemplazando servbay-vitepress-test.prod por tu dominio real y el directorio raíz por tu ruta correspondiente:
- macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
- Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

bash

# Reemplaza por tu dominio real, por ejemplo vitepress-cleanurl.servbay.demo
vitepress-cleanurl.servbay.demo {
    # Activa la compresión Brotli (zstd) y Gzip para mayor rapidez
    encode zstd gzip

    # Importar la configuración de logs por defecto de ServBay (útil para depuración)
    import set-log vitepress-cleanurl.servbay.demo

    # Gestión automática de certificados internos SSL de ServBay
    tls internal

    # Configuración clave: buscar el archivo adecuado
    # 1. Busca la ruta directamente (ej.: /about -> /about)
    # 2. Busca index.html dentro del directorio (ej.: /guide/ -> /guide/index.html)
    # 3. Busca archivos con extensión .html (ej.: /about -> /about.html)
    try_files {path} {path}/index.html {path}.html

    # Indicar el directorio raíz del sitio
    # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
    # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
    root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

    # Habilitar el servicio de archivos estáticos
    file_server
}

Guarda y aplica los cambios.

Acceder al sitio con URLs limpias
Ahora, al acceder al dominio configurado (por ejemplo, https://vitepress-cleanurl.servbay.demo), puedes navegar usando URLs sin la extensión .html; por ejemplo, para visitar la página about.html, simplemente accede a https://vitepress-cleanurl.servbay.demo/about.

Conclusión

Siguiendo esta guía, has aprendido cómo crear, desarrollar y desplegar sitios de documentación VitePress bajo el entorno ServBay. ServBay simplifica la gestión de Node.js y la configuración de servidores web locales, ya sea para desarrollo mediante proxy inverso o para producción sirviendo archivos estáticos, ofreciendo además dominios personalizados y certificados SSL integrados.

Aprovecha la potente combinación entre ServBay y VitePress para construir y mantener documentación técnica de alta calidad de forma eficiente.

Crear y ejecutar un proyecto VitePress con ServBay ​

¿Qué es VitePress? ​

Principales características y ventajas de VitePress ​

Crear y ejecutar un proyecto VitePress con ServBay ​

Requisitos previos ​

Crear el proyecto VitePress ​

Editar el contenido del proyecto VitePress ​

Entrar en modo desarrollo ​

Construir la versión de producción ​

Usar el modo de URLs limpias (cleanUrls: true) ​

Conclusión ​

Crear y ejecutar un proyecto VitePress con ServBay

¿Qué es VitePress?

Principales características y ventajas de VitePress

Crear y ejecutar un proyecto VitePress con ServBay

Requisitos previos

Crear el proyecto VitePress

Editar el contenido del proyecto VitePress

Entrar en modo desarrollo

Construir la versión de producción

Usar el modo de URLs limpias (`cleanUrls: true`)

Conclusión