Instalación y Configuración de Jigsaw en el Entorno ServBay

Descripción General

Este documento tiene como objetivo guiarte en la instalación y configuración de Jigsaw, un generador de sitios estáticos, dentro del potente entorno local de desarrollo web ServBay. ServBay proporciona un entorno integrado para diversas tecnologías como PHP y Node.js, lo que simplifica enormemente la puesta en marcha de proyectos Jigsaw. Gracias a ServBay, puedes configurar fácilmente dominios locales, HTTPS y servidores web eficientes para tus proyectos Jigsaw, permitiéndote enfocarte en el desarrollo del contenido de tu sitio.

¿Qué es Jigsaw?

Jigsaw es un generador de sitios estáticos construido sobre componentes de Laravel, desarrollado por la empresa Tighten. Aprovecha la potencia y flexibilidad del motor de plantillas Blade de Laravel y utiliza archivos Markdown para generar sitios HTML estáticos puros. Jigsaw es ideal para crear sitios de documentación, blogs, páginas de marketing o cualquier sitio web que no requiera una base de datos y procesamiento dinámico en el servidor. Sus principales ventajas son:

• Uso de herramientas familiares: Si ya conoces Laravel o las plantillas Blade, aprender Jigsaw será muy sencillo.
• Rendimiento y seguridad: Los sitios estáticos generados cargan rápidamente y, al no ejecutar código en el servidor, ofrecen mayor seguridad.
• Plantillas flexibles: Usando Blade puedes crear diseños y componentes complejos.
• Soporte para Markdown: Escribe el contenido fácilmente con Markdown.

Casos de Uso

Jigsaw es ideal para los siguientes escenarios:

• Sitios de documentación de proyectos y APIs
• Blogs personales o sitios de divulgación técnica
• Páginas de aterrizaje para empresas o productos
• Sitios web pequeños de presentación
• Cualquier web con altos requisitos de rendimiento y seguridad, y contenido relativamente estático

Requisitos Previos

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

1. ServBay instalado y en ejecución: Debes tener ServBay instalado y activo en tu sistema macOS. ServBay ya incluye PHP, Composer y Node.js/npm, esenciales para instalar y ejecutar Jigsaw.
2. Conocimientos básicos de la terminal: Necesitarás ejecutar algunos comandos en la terminal.
3. Conocimiento básico de Composer y npm: La instalación de Jigsaw depende de Composer y la compilación de recursos frontend usa npm.

Pasos de Instalación y Configuración

En esta sección encontrarás los pasos detallados para instalar y configurar un proyecto Jigsaw en el entorno ServBay.

Paso 1: Crear el Directorio del Proyecto

Primero, abre la terminal y navega al directorio raíz recomendado para sitios web en ServBay /Applications/ServBay/www. Allí, crea un nuevo subdirectorio para tu proyecto Jigsaw.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Nombramos el directorio del proyecto como servbay-jigsaw-demo, y aquí se almacenarán todos los archivos del proyecto.

Paso 2: Crear el Proyecto Jigsaw con Composer

ServBay ya tiene Composer preinstalado y configurado, así que puedes usar el comando composer directamente desde la terminal. Ahora, ejecuta el siguiente comando en tu directorio de proyecto (/Applications/ServBay/www/servbay-jigsaw-demo) para crear un proyecto Jigsaw:

composer create-project tightenco/jigsaw .

Este comando descargará la versión más reciente de Jigsaw y todas sus dependencias PHP en el directorio actual (.). Ten en cuenta que el punto final indica que el proyecto se creará en el directorio actual, en lugar de crear un subdirectorio llamado jigsaw.

Paso 3: Configurar el Sitio en ServBay

Para acceder a tu sitio Jigsaw a través del navegador web, es necesario configurar un sitio local en ServBay para este proyecto.

1. Abrir la interfaz de ServBay: Haz doble clic en el ícono de la app ServBay o ábrelo desde la barra de menú para acceder al panel de control.
2. Ir a "Sitios": En la barra lateral izquierda, haz clic en la pestaña "Sitios".
3. Agregar un nuevo sitio: Haz clic en el botón "+" en la parte inferior de la interfaz y selecciona "Añadir sitio".
4. Configurar los detalles del sitio:
   • Nombre: Ingresa un nombre fácil de reconocer, por ejemplo ServBay Jigsaw Demo.
   • Dominio: Especifica el dominio que utilizarás para acceder localmente. Se recomienda usar la terminación .servbay.demo para evitar conflictos con dominios reales, por ejemplo jigsaw-demo.servbay.demo. ServBay resolverá automáticamente los dominios .servbay.demo a tu máquina local.
   • Tipo de sitio: Selecciona PHP, ya que el proceso de construcción de Jigsaw requiere un entorno PHP.
   • Versión de PHP: Elige alguna de las versiones de PHP ya instaladas en ServBay; lo recomendable es utilizar una versión estable y reciente.
   • Directorio raíz del sitio: Este paso es crucial. Los archivos estáticos que genera Jigsaw por defecto se ubican en el directorio build_local dentro de la raíz del proyecto. Por tanto, apunta la raíz de tu sitio web a ese directorio de salida: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Guardar y aplicar: Una vez completada toda la información, haz clic en "Guardar". ServBay te pedirá confirmar la aplicación de los cambios; acepta para proceder. ServBay actualizará automáticamente la configuración del servidor web (Caddy o Nginx) y configurará el HTTPS por ti.

Paso 4: Instalar Dependencias Frontend

Por lo general, los proyectos Jigsaw utilizan npm para gestionar y compilar los recursos frontend (como los preprocesadores CSS SASS, archivos JavaScript, etc.). En el entorno ServBay, Node.js y npm ya están disponibles.

Ejecuta el siguiente comando en tu directorio de proyecto (/Applications/ServBay/www/servbay-jigsaw-demo) para instalar las dependencias frontend:

npm install

Este comando leerá el archivo package.json del proyecto y descargará todos los módulos necesarios de Node.js en el directorio node_modules.

Paso 5: Construir el Sitio Jigsaw

Tras instalar todas las dependencias, ejecuta el comando de construcción de Jigsaw para generar los archivos estáticos del sitio.

En el directorio del proyecto, ejecuta:

./vendor/bin/jigsaw build

Este comando hará lo siguiente:

1. Procesará los archivos Markdown y las plantillas Blade dentro del directorio source.
2. Correrá las tareas de compilación definidas en webpack.mix.js (si npm install incluyó Laravel Mix).
3. Guardará el HTML, CSS, JS y los demás archivos generados en el directorio build_local.

Paso 6: Acceder al Sitio Web

Ahora que los archivos estáticos del sitio Jigsaw se encuentran en /Applications/ServBay/www/servbay-jigsaw-demo/build_local y tienes la raíz del sitio configurada en ServBay a esa ubicación, ya puedes acceder a tu sitio desde el navegador.

Abre tu navegador web y accede al dominio configurado en el paso 3, por ejemplo https://jigsaw-demo.servbay.demo. ServBay gestionará automáticamente los certificados HTTPS locales (mediante ServBay User CA) y deberías ver la página de bienvenida por defecto de Jigsaw.

Personalización y Desarrollo

Con el entorno básico ya listo, puedes comenzar a personalizar el contenido y los estilos de tu sitio Jigsaw.

Editar Contenido y Plantillas

• El código fuente del sitio está en el directorio source en la raíz de tu proyecto.
• Los layouts y componentes HTML, escritos en Blade, se encuentran en las subcarpetas source/_layouts y source/_partials.
• El contenido de las páginas generalmente se escribe en Markdown, alojado en el directorio source o en subcarpetas (por ejemplo, source/index.md, source/about.md).
• Las entradas del blog suelen estar en source/_posts, y siguen el formato YYYY-MM-DD-slug.md para nombrarlas.

Agregar Nuevas Páginas/Publicaciones

Para añadir una nueva página o entrada de blog, simplemente crea un nuevo archivo Markdown en el directorio source o en sus subcarpetas correspondientes (como source/_posts).

Por ejemplo, para crear una página "Acerca de", agrega el archivo source/about.md:

---
title: "Sobre nosotros"
description: "Descubre más sobre ServBay Jigsaw Demo"
---

# Sobre nosotros

Esta es una página About construida con Jigsaw.

Aquí puedes agregar información sobre la empresa, el equipo, etc.

Personalizar Estilos y Scripts

Jigsaw suele utilizar Laravel Mix (webpack.mix.js) para compilar los recursos de frontend.

• Los archivos de estilos (usualmente SASS/SCSS) se guardan en source/_assets/sass.
• Los archivos JavaScript se almacenan en source/_assets/js.

En el directorio del proyecto, puedes utilizar los siguientes scripts npm para compilar estos recursos:

• npm run dev: Compila los recursos de desarrollo (incluye Source Maps, no minifica).
• npm run watch: Compila recursos para desarrollo y observa los cambios; recompila automáticamente. Muy útil durante el desarrollo.
• npm run prod: Compila recursos para producción con minificación y optimización.

Por ejemplo, tras modificar source/_assets/sass/main.scss, ejecuta npm run dev o npm run watch para generar el CSS correspondiente.

Reconstruir el Sitio

Nota importante: Cada vez que modifiques archivos de contenido (Markdown) o plantillas (Blade) dentro del directorio source, es necesario volver a ejecutar el comando de construcción de Jigsaw para actualizar los archivos estáticos en build_local:

./vendor/bin/jigsaw build

Si modificaste recursos frontend (SASS, JS), ejecuta npm run dev o npm run watch para recompilar estos assets. En la mayoría de los proyectos Jigsaw, el comando build también dispara la compilación de Mix, aunque mantenerlo separado ayuda cuando necesitas depurar.

Aspectos a Tener en Cuenta

• Directorio de salida: Por defecto, Jigsaw genera el sitio en build_local (desarrollo) y build_production (producción). Asegúrate que la raíz de tu sitio en ServBay apunte al directorio que deseas (habitualmente, en desarrollo es build_local).
• Servidor web: ServBay emplea Caddy o Nginx como servidor web, sirviendo directamente los archivos estáticos en build_local con excelente rendimiento. No es necesario usar el comando integrado jigsaw serve (principalmente pensado para previews rápidos y menos potente que el servidor web completo de ServBay).
• HTTPS: ServBay configura automáticamente el HTTPS para dominios .servbay.demo y firma los certificados con ServBay User CA. Posiblemente necesites confiar en dicha CA en tu sistema para evitar advertencias del navegador.
• Compilación limpia: Si experimentas problemas extraños durante la construcción, intenta una compilación limpia ejecutando ./vendor/bin/jigsaw build --clean.

Preguntas Frecuentes (FAQ)

P: Modifiqué un archivo Markdown pero no veo los cambios en el navegador.

R: Tras modificar contenido o plantillas, debes ejecutar en la terminal el comando ./vendor/bin/jigsaw build para reconstruir el sitio.

P: He editado archivos SCSS pero los estilos no cambian.

R: Tras modificar assets de frontend, ejecuta en el directorio del proyecto npm run dev o npm run watch para recompilar los recursos.

P: Al visitar el dominio local, me aparece “No se puede acceder” o “Archivo no encontrado”.

R: Verifica los siguientes puntos:

1. Asegúrate que ServBay esté en ejecución.
2. Revisa la configuración del sitio en ServBay: ¿el dominio es correcto? ¿la raíz apunta a /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Comprueba que ejecutaste con éxito el comando ./vendor/bin/jigsaw build y que el directorio build_local contiene archivos estáticos generados (por ejemplo index.html).

P: ¿Cómo despliego un sitio Jigsaw?

R: Jigsaw genera solo archivos estáticos. El proceso habitual es:

1. Ejecuta ./vendor/bin/jigsaw build production para crear los archivos optimizados para producción.
2. Sube todos los archivos de build_production a cualquier proveedor que soporte hosting de sitios estáticos (Netlify, Vercel, GitHub Pages, distintos almacenamientos en la nube, etc).

Resumen

ServBay hace que instalar y configurar el generador de sitios estáticos Jigsaw en macOS sea extraordinariamente eficiente y simple. Proporciona todo el entorno necesario (PHP, Composer, Node.js, npm) y una potente configuración para servidores web locales. Siguiendo esta guía, puedes iniciar rápidamente un proyecto Jigsaw y aprovechar las funcionalidades de ServBay para optimizar tu flujo de desarrollo local.