Criando e executando projetos VitePress com o ServBay

O VitePress é um gerador de sites estáticos moderno, impulsionado pelo Vue, projetado para construir sites de documentação rápidos, atraentes e de fácil manutenção. Baseado no Vite, ele oferece uma experiência de desenvolvimento e performance de build excepcionais. Para desenvolvedores que precisam criar uma documentação profissional para projetos, bibliotecas ou produtos, o VitePress é uma excelente escolha.

Durante o desenvolvimento e teste de sites VitePress localmente, é essencial contar com um ambiente web de fácil configuração e estável. O ServBay foi desenhado para esse cenário, integrando múltiplas versões de Node.js e servidores web robustos (como Caddy ou Nginx), facilitando a execução de projetos VitePress no seu ambiente local.

Este guia mostra como criar, configurar e executar um projeto VitePress do zero usando o ambiente integrado do ServBay, incluindo como configurar o proxy reverso para o servidor de desenvolvimento e hospedar arquivos estáticos do build de produção.

O que é VitePress?

O VitePress é um gerador de site estático (SSG) baseado no Vite, aproveitando o poder do Vue 3 e a velocidade do Vite para geração de sites estáticos, sendo especialmente indicado para documentação técnica.

Principais recursos e vantagens do VitePress

• Desenvolvimento super-rápido: Com o Hot Module Replacement (HMR) do Vite, qualquer alteração no conteúdo aparece praticamente instantaneamente no navegador, tornando o fluxo de trabalho altamente eficiente.
• Baseado em Vue: Permite utilizar componentes Vue diretamente nos arquivos Markdown, o que traz interatividade e flexibilidade ao seu conteúdo de documentação.
• Simplicidade: Configuração descomplicada, pronto para uso e focado na escrita do conteúdo.
• Alto desempenho: Gera arquivos estáticos leves e rápidos de carregar, proporcionando uma experiência fluida de SPA graças ao roteamento embutido no cliente.
• SEO amigável: Estrutura HTML otimizada para buscadores e suporte a customização de meta tags.
• Markdown aprimorado: Suporte completo ao CommonMark e GitHub Flavored Markdown (GFM), além de sintaxes extras.

Com o VitePress, desenvolvedores podem facilmente criar sites de documentação de alta qualidade e performance.

Criando e executando um projeto VitePress usando ServBay

O ServBay fornece um jeito prático de gerenciar múltiplas versões do Node.js e configurar servidores web para servir o seu projeto VitePress, tanto no modo de desenvolvimento quanto de produção.

Pré-requisitos

Antes de começar, garanta que você já possui estes requisitos:

1. ServBay instalado: O ServBay deve estar instalado corretamente no seu sistema macOS. Caso ainda não tenha feito isso, siga o Guia de Instalação do ServBay.
2. Pacote Node.js instalado: Certifique-se de ter instalado e habilitado a versão necessária do Node.js pelo ServBay, na página "Pacotes" do painel de controle. Consulte Usando o Node.js.

Criando o projeto VitePress

1. Inicialize o diretório do projeto

   Abra seu terminal. Recomendamos criar a pasta do projeto sob o diretório raiz padrão do ServBay /Applications/ServBay/www para facilitar a configuração posterior do ServBay:

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

2. Instale o VitePress e inicialize a configuração

   No diretório do projeto, utilize npm ou yarn para instalar o VitePress como dependência de desenvolvimento e rode o comando de inicialização:

   npm add -D vitepress
   npx vitepress init

   Ou com Yarn:

   yarn add -D vitepress
   yarn vitepress init

   O comando de inicialização irá guiá-lo através de algumas configurações básicas, como o título e descrição do site. Siga o passo a passo:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Diretório padrão de documentação, apenas tecle Enter
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Digite o título do seu site, exemplo: ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Digite a descrição do site
    │
    ◇  Theme:
    │  Default Theme # Escolha o tema, o padrão já é adequado
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Deseja configurar em TypeScript? Escolha conforme sua preferência
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Adicionar scripts ao package.json, recomendado escolher Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

   Após a inicialização, o VitePress cria um subdiretório docs com arquivos de configuração padrão (.vitepress) e páginas exemplo (index.md, guide/index.md, etc.). O package.json também será atualizado com os scripts docs:dev e docs:build.

Editando o conteúdo do VitePress

1. Edite o conteúdo da página inicial

   O arquivo inicial padrão do VitePress está em docs/index.md. Abra com seu editor favorito e modifique, por exemplo:

   # Hello ServBay!
   
   Bem-vindo ao uso do ServBay para rodar seu site de documentação VitePress.
   
   Este é um site de demonstração local criado com VitePress e servido via ServBay.

Modo de desenvolvimento

Durante o desenvolvimento do site VitePress, geralmente utilizamos seu servidor de desenvolvimento embutido, que oferece hot-reload para pré-visualização instantânea das mudanças. Com o ServBay, você pode acessar esse servidor com um domínio personalizado e SSL através do recurso de proxy reverso.

1. Execute o servidor de desenvolvimento do VitePress

   Certifique-se de estar no diretório raiz do projeto /Applications/ServBay/www/servbay-vitepress-app e execute:

   npm run docs:dev -- --port 8585

   Ou com Yarn:

   yarn docs:dev --port 8585

   O servidor estará em execução na porta especificada (por exemplo, 8585). O terminal irá mostrar o endereço local, geralmente http://localhost:8585.

2. Configure o site no ServBay (Proxy Reverso)

   Abra o painel do ServBay e vá até a seção "Sites". Adicione uma nova configuração de site:

   • Nome: Um identificador fácil, por exemplo VitePress Site de Desenvolvimento.
   • Domínio: Escolha um domínio local para desenvolvimento. Para evitar conflitos e seguir os padrões ServBay, use o sufixo .servbay.demo, como vitepress-dev.servbay.demo.
   • Tipo de site: Selecione Proxy reverso.
   • IP: Preencha com 127.0.0.1 (localhost).
   • Porta: Use a porta definida no passo 1 (ex: 8585).

   Salve e aplique as alterações. O ServBay irá configurar automaticamente o servidor web (Caddy ou Nginx) para encaminhar os pedidos do domínio https://vitepress-dev.servbay.demo para http://127.0.0.1:8585.

3. Acesse o site de desenvolvimento

   Agora acesse https://vitepress-dev.servbay.demo no navegador. Você verá o site servido pelo servidor de desenvolvimento do VitePress. O ServBay oferece domínio personalizado e certificado SSL assinado pela sua User CA, garantindo acesso HTTPS seguro.

Build de produção

Quando seu site de documentação estiver pronto para publicação, é hora de gerar a versão estática otimizada.

1. Gere a versão de produção

   Certifique-se de estar na raiz /Applications/ServBay/www/servbay-vitepress-app e rode:

   npm run docs:build

   Ou com Yarn:

   yarn docs:build

   O processo irá compilar seus arquivos Markdown, componentes Vue, etc, em arquivos HTML, CSS e JavaScript otimizados, que vão para o diretório docs/.vitepress/dist.

2. Configure o site no ServBay (Serviço de arquivos estáticos)

   Um site VitePress de produção consiste apenas em arquivos estáticos, então você pode servi-los diretamente com o ServBay.

   No painel do ServBay, em "Sites", crie uma nova configuração:

   • Nome: Algo que identifique como site de produção, ex: VitePress Site de Produção.
   • Domínio: Escolha o domínio local, exemplo: vitepress-prod.servbay.demo.
   • Tipo de site: Selecione Estático.
   • Diretório raiz: Defina o caminho absoluto da pasta de build: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Salve e aplique as alterações. O ServBay configurará o servidor para servir diretamente os arquivos estáticos.

3. Acesse o site de produção

   No navegador, acesse https://vitepress-prod.servbay.demo. O conteúdo do build de produção estará disponível com domínio personalizado e certificado SSL providos automaticamente pelo ServBay.

Utilizando o modo de URL limpa (cleanUrls: true)

O VitePress suporta a configuração cleanUrls: true para gerar links sem a extensão .html (exemplo: /guide/ ao invés de /guide/index.html). Para que o servidor web responda corretamente a esses links, configurações adicionais são necessárias.

O ServBay usa Caddy ou Nginx como servidores web. Veja abaixo um exemplo de configuração para Caddy, explorando a diretiva try_files para procurar arquivos e redirecionar para índices ou extensões .html:

1. Ative o cleanUrls na configuração do VitePress

   No arquivo de configuração (docs/.vitepress/config.mts ou docs/.vitepress/config.ts), adicione ou altere a opção cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... outras configurações
     cleanUrls: true, // Habilita URLs limpas
     // ... outras configurações
   })

   Em seguida, recompile com npm run docs:build.

2. Configure site ServBay (Caddy customizado)

   No painel ServBay, em "Sites", encontre o domínio do site de produção (por exemplo, vitepress-prod.servbay.demo).

   • Clique em editar.
   • Marque a opção Configuração personalizada.
   • Insira o seguinte exemplo de configuração Caddy, substituindo vitepress-cleanurl.servbay.demo pelo domínio real e ajustando o caminho do diretório raíz se necessário:

   # Substitua pelo seu domínio real, ex: vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Ativa compressão Brotli (zstd) e Gzip para acelerar carregamento
       encode zstd gzip
   
       # Importa configuração padrão de logs do ServBay (para debugging)
       import set-log vitepress-cleanurl.servbay.demo
   
       # Configura SSL interno gerenciado pelo ServBay
       tls internal
   
       # Lógica: tenta acessar
       # 1. O caminho direto (ex: /about -> /about)
       # 2. index.html no diretório (/guide/ -> /guide/index.html)
       # 3. Arquivo com extensão .html (/about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Diretório raiz do site
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Serviço de arquivos estáticos habilitado
       file_server
   }

   Salve e aplique.

3. Acesse o site com URLs limpas

   Agora basta acessar o domínio configurado (ex: https://vitepress-cleanurl.servbay.demo). Para páginas que antes teriam .html no final, utilize URLs sem extensão, como https://vitepress-cleanurl.servbay.demo/about.

Resumo

Seguindo este tutorial, você agora sabe como criar, desenvolver e publicar sites de documentação VitePress no ambiente gerenciado do ServBay. O ServBay simplifica o gerenciamento do Node.js e a configuração de servidores web locais, seja para proxy reverso no desenvolvimento ou para servir arquivos estáticos em produção, sempre com suporte automático a domínios personalizados e certificados SSL.

Aproveite a combinação poderosa de ServBay e VitePress para construir e manter documentação técnica de alta qualidade com mais eficiência.