Instalando e Configurando o Jigsaw no Ambiente do ServBay

Visão Geral

Este documento tem como objetivo guiá-lo na instalação e configuração do gerador de sites estáticos Jigsaw no poderoso ambiente de desenvolvimento web local ServBay. O ServBay oferece um ambiente integrado para várias stacks de tecnologias como PHP e Node.js, tornando muito mais simples a preparação de projetos Jigsaw. Com o ServBay, você pode configurar facilmente domínios locais, HTTPS e servidores web eficientes para seus projetos Jigsaw, permitindo que você foque no desenvolvimento do conteúdo do seu site.

O que é o Jigsaw?

Jigsaw é um gerador de sites estáticos baseado em componentes do Laravel, desenvolvido pela empresa Tighten. Ele aproveita todo o poder e flexibilidade do mecanismo de templates Blade do Laravel, junto com arquivos Markdown, para gerar sites HTML estáticos puros. O Jigsaw é ideal para criação de sites de documentação, blogs, landing pages de marketing ou qualquer site estático que não precise de banco de dados backend ou processamento dinâmico no servidor. Seus principais benefícios incluem:

• Uso de ferramentas familiares: Se você já conhece Laravel ou os templates Blade, vai se adaptar rapidamente ao Jigsaw.
• Performance e segurança: Os sites estáticos gerados carregam rapidamente e são mais seguros, pois não há execução de código no servidor.
• Templates flexíveis: Com o Blade, você pode criar layouts e componentes complexos.
• Suporte a Markdown: Escreva conteúdos de forma simples e eficiente.

Casos de Uso

O Jigsaw é indicado para situações como:

• Sites de documentação de projetos e APIs
• Blogs pessoais ou portais de compartilhamento técnico
• Landing pages de marketing para empresas ou produtos
• Pequenos sites institucionais ou de portfólio
• Qualquer site com alto foco em performance, segurança e conteúdo estático

Pré-Requisitos

Antes de começar, certifique-se de que:

1. ServBay esteja instalado e em funcionamento: Você precisa ter o ServBay rodando no macOS. O ServBay já vem com PHP, Composer e Node.js/npm prontos para uso, essenciais para instalação e execução do Jigsaw.
2. Conhecimento básico de terminal: Você precisará executar alguns comandos no terminal.
3. Noções básicas sobre Composer e npm: O Jigsaw é instalado via Composer e os recursos front-end são compilados com o npm.

Passo a Passo de Instalação e Configuração

Esta seção detalha cada etapa para instalar e configurar um projeto Jigsaw no ambiente do ServBay.

Passo 1: Criar o Diretório do Projeto

Primeiro, abra o terminal, navegue até o diretório raiz recomendado pelo ServBay para sites (/Applications/ServBay/www) e crie uma nova pasta para seu projeto Jigsaw.

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

Vamos chamar o diretório do projeto de servbay-jigsaw-demo. Todos os arquivos do projeto ficarão nesta pasta.

Passo 2: Criar o Projeto Jigsaw com Composer

O ServBay já vem com o Composer pré-instalado e configurado, então você pode usar o comando composer diretamente. Agora, estando no diretório do projeto (/Applications/ServBay/www/servbay-jigsaw-demo), execute:

composer create-project tightenco/jigsaw .

Esse comando baixa a versão mais recente do Jigsaw e todas as dependências PHP para o diretório atual (.). O ponto final indica que o projeto será criado no diretório atual, não criando uma subpasta chamada jigsaw.

Passo 3: Configurar o Site no ServBay

Para acessar seu site Jigsaw pelo navegador, é preciso configurar um site local no ServBay.

1. Abra o ServBay UI: Clique duas vezes no ícone do aplicativo ServBay ou acesse pelo ícone na barra de menus.
2. Vá em “Sites”: Na barra lateral esquerda, clique na aba “Sites”.
3. Adicione um novo site: Clique no botão “+” na parte inferior e escolha “Adicionar Site”.
4. Preencha os detalhes do site:
   • Nome: Use um nome fácil de identificar, por exemplo ServBay Jigsaw Demo.
   • Domínio: Escolha um domínio local, recomendando o sufixo .servbay.demo para evitar conflitos, como jigsaw-demo.servbay.demo. O ServBay faz a resolução automaticamente desse domínio para o localhost.
   • Tipo de Site: Escolha PHP, pois o Jigsaw requer ambiente PHP para o build.
   • Versão do PHP: Selecione uma das versões instaladas no ServBay, preferencialmente a mais recente e estável.
   • Raiz do site: Muito importante! O Jigsaw gera os arquivos estáticos no diretório build_local dentro do projeto, então a raiz deve ser apontada para: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Salve e aplique: Depois de preencher tudo, clique em “Salvar”. O ServBay solicitará confirmação para aplicar as mudanças: confirme. O ServBay atualizará automaticamente as configurações do servidor web (Caddy ou Nginx) e ativará o HTTPS.

Passo 4: Instalar Dependências Front-end

Projetos Jigsaw geralmente usam o npm para gerenciar e compilar ativos front-end (SASS, JavaScript etc.). No ServBay, Node.js e npm já estão prontos para uso.

No diretório do projeto (/Applications/ServBay/www/servbay-jigsaw-demo), execute:

npm install

Isso lê o arquivo package.json do projeto, baixando os módulos Node.js necessários para a pasta node_modules.

Passo 5: Gerar o Site Jigsaw

Com todas as dependências instaladas, rode o comando de build do Jigsaw para gerar os arquivos estáticos do site.

Ainda no diretório do projeto, execute:

./vendor/bin/jigsaw build

Esse comando irá:

1. Processar os arquivos Markdown e templates Blade em source.
2. Rodar as tarefas definidas em webpack.mix.js (caso o projeto use Laravel Mix via npm install).
3. Gerar todos os arquivos HTML, CSS, JS e outros assets estáticos na pasta build_local.

Passo 6: Acessar o Site

Agora que os arquivos do site foram gerados em /Applications/ServBay/www/servbay-jigsaw-demo/build_local e a raiz do site no ServBay está apontada para lá, você já pode acessar o domínio local configurado.

Abra o navegador e digite o domínio cadastrado no Passo 3, por exemplo: https://jigsaw-demo.servbay.demo. O ServBay gerencia automaticamente os certificados HTTPS (usando a ServBay User CA). Você deverá ver a página de boas-vindas padrão do Jigsaw.

Customização e Desenvolvimento

Com o ambiente configurado e em funcionamento, você pode começar a customizar o conteúdo e o design do seu site Jigsaw.

Editando Conteúdo e Templates

• O código-fonte do site está dentro da pasta source no diretório do projeto.
• Os layouts HTML e componentes usam Blade e ficam em source/_layouts, source/_partials e subpastas correlatas.
• O conteúdo das páginas normalmente está em arquivos Markdown em source ou seus subdiretórios (ex: source/index.md, source/about.md).
• Posts de blog geralmente ficam em source/_posts, nomeados como YYYY-MM-DD-slug.md.

Adicionando Novas Páginas/Postagens

Para adicionar uma nova página ou post de blog, crie um novo arquivo Markdown em source ou na subpasta apropriada (como source/_posts).

Exemplo para criar um arquivo source/about.md:

---
title: "Sobre Nós"
description: "Saiba mais sobre o ServBay Jigsaw Demo"
---

# Sobre Nós

Esta é uma página “Sobre” criada com o Jigsaw.

Aqui você pode adicionar informações sobre a empresa, equipe, etc.

Personalizando Estilos e Scripts

Projetos Jigsaw geralmente utilizam o Laravel Mix (webpack.mix.js) para compilar os recursos front-end.

• Arquivos de estilo (normalmente SASS/SCSS) estão em source/_assets/sass.
• Arquivos JavaScript estão em source/_assets/js.

No diretório do projeto, use scripts npm para compilar os assets:

• npm run dev: compila os assets em modo desenvolvimento, com Source Maps, sem minificação.
• npm run watch: compila e fica observando alterações nos arquivos, recompilando automaticamente — ideal durante o desenvolvimento.
• npm run prod: compila para produção com minificação e otimizações.

Se você alterar o source/_assets/sass/main.scss, por exemplo, basta rodar npm run dev ou npm run watch para atualizar o CSS correspondente.

Reconstruindo o Site

Importante: Sempre que alterar arquivos de conteúdo (Markdown) ou templates (Blade) na pasta source, execute novamente o comando de build para que o Jigsaw processe as mudanças e atualize os arquivos na build_local:

./vendor/bin/jigsaw build

Se for alterar arquivos front-end (SASS, JS), execute npm run dev ou npm run watch para recompilar os assets. Em muitos projetos, o comando build do Jigsaw já aciona o Mix, mas compreender os fluxos separadamente ajuda a depurar e otimizar o processo.

Dicas e Observações

• Diretório de saída: O Jigsaw gera arquivos estáticos em build_local (desenvolvimento) e build_production (produção). Para desenvolvimento local, aponte a raiz do site do ServBay para build_local.
• Servidor web: O ServBay usa Caddy ou Nginx como servidor web, servindo diretamente os arquivos de build_local com alta performance. Não é necessário usar jigsaw serve — ele é mais limitado e menos robusto que o servidor do ServBay.
• HTTPS: O ServBay configura automaticamente HTTPS para domínios .servbay.demo e usa a ServBay User CA para assinar os certificados. Para evitar alertas no navegador, confie no certificado ServBay User CA no seu sistema.
• Build limpo: Se encontrar problemas estranhos durante o build, tente rodar ./vendor/bin/jigsaw build --clean para uma recompilação limpa.

Perguntas Frequentes (FAQ)

P: Alterei um arquivo Markdown, mas não vejo as mudanças no navegador. O que fazer?

R: Execute ./vendor/bin/jigsaw build no terminal após modificar um conteúdo ou template para regenerar o site.

P: Alterei um arquivo SCSS e o estilo não mudou no site. Por quê?

R: Após modificar assets front-end, rode npm run dev ou npm run watch dentro do projeto para recompilar os recursos.

P: Ao tentar abrir o domínio local, aparece 'impossível acessar' ou 'arquivo não encontrado'. O que verifico?

R: Confira:

1. O ServBay está rodando?
2. As configurações do site dentro do ServBay estão corretas? Domínio e raiz apontam para /Applications/ServBay/www/servbay-jigsaw-demo/build_local?
3. Você rodou ./vendor/bin/jigsaw build com sucesso e o diretório build_local contém os arquivos (como index.html)?

P: Como faço o deploy do site Jigsaw?

R: O Jigsaw gera arquivos estáticos. O fluxo normalmente é:

1. Execute ./vendor/bin/jigsaw build production para gerar os arquivos otimizados de produção.
2. Faça upload de todos os arquivos do build_production para um provedor de hospedagem que aceite sites estáticos (Netlify, Vercel, GitHub Pages, cloud storage, etc.).

Resumo

Usando o ServBay, instalar e configurar o gerador de sites estáticos Jigsaw no macOS torna-se rápido e prático. O ServBay oferece todo o ambiente necessário (PHP, Composer, Node.js, npm), além de um servidor web local robusto. Siga este passo a passo para iniciar seu projeto Jigsaw rapidamente e aproveite os recursos do ServBay para potencializar e agilizar seu fluxo de desenvolvimento local.