Como Criar e Executar Projetos VitePress com ServBay

VitePress é um gerador moderno de sites estáticos, impulsionado pelo Vue, projetado para criar sites de documentação rápidos, bonitos e fáceis de manter. Construído sobre o Vite, oferece uma experiência de desenvolvimento excepcional e ótimo desempenho na construção. Para desenvolvedores que precisam criar documentação profissional para projetos, bibliotecas ou produtos, VitePress é uma escolha excelente.

Durante o desenvolvimento e teste local com VitePress, um ambiente Web confiável e de fácil configuração é essencial. O ServBay foi criado exatamente para este propósito: ele integra diversas versões do Node.js e servidores Web robustos (como Caddy ou Nginx), facilitando o serviço dos seus projetos VitePress.

Neste guia, você vai aprender como usar o ambiente integrado do ServBay para criar, configurar e rodar um projeto VitePress do zero, incluindo ajustes de proxy reverso para o servidor de desenvolvimento e serviço de arquivos estáticos para produção.

O que é VitePress?

VitePress é um gerador de site estático (SSG) baseado no Vite, que aproveita o poder do Vue 3 e a velocidade do Vite para criar sites estáticos, especialmente voltado para documentação técnica.

Principais características e benefícios do VitePress

• Desenvolvimento ultrarrápido: Graças ao Hot Module Replacement (HMR) do Vite, as modificações aparecem quase instantaneamente no navegador, tornando o fluxo de trabalho extremamente ágil.
• Impulsionado pelo Vue: Permite usar componentes Vue diretamente em arquivos Markdown, aumentando interatividade e flexibilidade da documentação.
• Fácil de usar: Configuração simples e pronta para uso, com foco total na criação de conteúdo.
• Alto desempenho: Gera arquivos estáticos leves, rápido de carregar e, com roteamento cliente integrado, proporciona experiência fluida de SPA.
• SEO amigável: A estrutura HTML gerada facilita o rastreamento por motores de busca, além de permitir customização de tags de cabeçalho.
• Markdown aprimorado: Suporte total ao CommonMark e GitHub Flavored Markdown (GFM), além de sintaxe extra exclusiva.

Com VitePress, você constrói facilmente sites de documentação de alta qualidade e desempenho.

Como Criar e Rodar Projetos VitePress com ServBay

ServBay oferece uma forma prática de gerenciar versões do Node.js e configurar o servidor Web para seu projeto VitePress — seja no modo desenvolvimento ou servindo arquivos estáticos na produção.

Pré-requisitos

Antes de começar, certifique-se de:

1. Instalar o ServBay: O ServBay já está instalado no seu sistema. Caso precise instalar, consulte o Guia de Instalação do ServBay.
2. Instalar pacote Node.js: No ServBay, verifique se a versão necessária do Node.js está instalada e ativada. Gerencie isso pela página "Pacotes" no painel ServBay. Veja mais detalhes em Usando Node.js.

Criando o Projeto VitePress

1. Inicialize a pasta do projeto

   Abra o terminal. É recomendado criar a pasta do projeto no diretório raiz padrão de sites do ServBay, facilitando a configuração posterior.

   macOS:

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

   Windows:

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Instale VitePress e configure o projeto

   No diretório servbay-vitepress-app, instale VitePress como dependência de desenvolvimento usando npm ou yarn, 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 processo de inicialização irá guiá-lo pelas configurações básicas como título do site e descrição. Siga as instruções:

    ┌  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 # Título do site, ex: ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Descrição do site
    │
    ◇  Theme:
    │  Default Theme # Mantenha o tema padrão
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Configurar com TypeScript, escolha conforme preferência
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Recomenda-se adicionar os scripts ao package.json
    │
    └  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 (.vitepress) e páginas de exemplo (index.md, guide/index.md). O arquivo package.json também é atualizado com scripts úteis como docs:dev e docs:build.

Editando o Conteúdo do Projeto VitePress

1. Editar a página inicial

   O arquivo inicial padrão (docs/index.md) pode ser editado em qualquer editor de texto. Por exemplo, você pode atualizar para:

   # Olá ServBay!
   
   Bem-vindo ao ServBay para rodar seu site de documentação VitePress.
   
   Este é um site de demonstração local criado com VitePress e servido pelo ServBay.

Entrando no Modo de Desenvolvimento

Durante o desenvolvimento do site VitePress, usa-se o servidor embutido que oferece hot reload, permitindo pré-visualizações instantâneas. Além disso, o ServBay oferece proxy reverso para acessar este servidor via domínio personalizado e com SSL fornecido automaticamente.

1. Rodar servidor de desenvolvimento VitePress

   No terminal — diretório raiz do projeto (macOS: /Applications/ServBay/www/servbay-vitepress-app; Windows: C:\ServBay\www\servbay-vitepress-app). Execute para iniciar o servidor de desenvolvimento e defina a porta (ex: 8585).

   npm run docs:dev -- --port 8585

   Ou com Yarn:

   yarn docs:dev --port 8585

   O servidor estará disponível em http://localhost:8585.

2. Configurar site ServBay (proxy reverso)

   No painel ServBay, vá até "Sites" e crie uma nova configuração.

   • Nome: Ex: Site de Desenvolvimento VitePress.
   • Domínio: Escolha de acordo com a recomendação ServBay, como vitepress-dev.servbay.demo.
   • Tipo de site: Proxy reverso.
   • IP: 127.0.0.1 (localhost).
   • Porta: Use a porta especificada no passo anterior, como 8585.

   Salve e aplique as alterações. O ServBay vai configurar o servidor Web para redirecionar as requisições de https://vitepress-dev.servbay.demo para http://127.0.0.1:8585.

3. Acessar o site de desenvolvimento

   Agora, abra https://vitepress-dev.servbay.demo no navegador. Você verá o conteúdo do seu site servido pelo VitePress em modo desenvolvimento. O domínio customizado e o certificado SSL são gerados e gerenciados automaticamente pelo ServBay User CA.

Gerando a Versão de Produção

Quando sua documentação estiver pronta para publicação, gere a versão otimizada estática.

1. Build da versão de produção

   No terminal, diretório raiz do projeto, rode:

   npm run docs:build

   Ou com Yarn:

   yarn docs:build

   Os arquivos estáticos finais são gerados em docs/.vitepress/dist.

2. Configurar site ServBay (arquivos estáticos)

   Agora, vá ao painel ServBay, seção "Sites", e crie nova configuração:

   • Nome: Ex: Site de Produção VitePress.
   • Domínio: Por exemplo, vitepress-prod.servbay.demo.
   • Tipo de site: Estático.
   • Raiz do site: Direcione para o caminho dos arquivos estáticos:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Salve e aplique as alterações. O ServBay vai servir os arquivos do diretório especificado pelo servidor Web.

3. Acessar o site de produção

   Abra no navegador https://vitepress-prod.servbay.demo. Seu site estático VitePress já está acessível, com domínio customizado e SSL automático providos pelo ServBay.

Executando com URLs Limpos (cleanUrls: true)

O VitePress suporta a configuração cleanUrls: true, ou seja, as URLs dos sites não têm extensão .html (ex: /about ao invés de /about.html). Para funcionar corretamente, é necessário ajustar o servidor Web.

ServBay usa Caddy ou Nginx. Abaixo um exemplo de configuração para Caddy, usando try_files para buscar o arquivo correto (com ou sem .html):

1. Ativar cleanUrls no VitePress

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

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... outros configs
     cleanUrls: true, // Ativa URLs limpas
     // ... outros configs
   })

   Gere novamente a versão de produção com npm run docs:build.

2. Configurar site ServBay (Caddy customizado)

   No painel ServBay, edite o site configurado para produção (ex: vitepress-prod.servbay.demo).

   • Clique para editar.
   • Marque a opção Configuração personalizada.
   • Cole na área de configuração Caddy o conteúdo abaixo, alterando o domínio e o caminho conforme seu ambiente:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Altere para 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 de log padrão do ServBay
       import set-log vitepress-cleanurl.servbay.demo
   
       # Gera e gerencia certificado SSL interno do ServBay
       tls internal
   
       # Configuração central: busca sequencial dos arquivos
       # 1. Tenta caminho direto (ex: /about -> /about)
       # 2. Busca index.html no diretório (ex: /guide/ -> /guide/index.html)
       # 3. Busca arquivo .html (ex: /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Define a raiz do site
       # 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
   
       # Habilita serviço de arquivos estáticos
       file_server
   }

   Salve e finalize a configuração.

3. Acessar o site com URLs limpas

   Agora, acesse seu domínio (ex: https://vitepress-cleanurl.servbay.demo). As páginas configuradas com cleanUrls estarão disponíveis através de URLs sem extensão, como /about ao invés de /about.html.

Conclusão

Com este guia, você aprendeu a criar, desenvolver e publicar sites de documentação VitePress utilizando o ambiente ServBay. O ServBay simplifica o gerenciamento do Node.js, configuração do servidor Web local e oferece facilidade para configurar proxy reverso em desenvolvimento e serviço estático em produção — tudo com domínio personalizado e SSL automatizado.

Aproveite a combinação poderosa do ServBay com VitePress para construir e manter documentação técnica de alta qualidade com muito mais agilidade.