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:
- 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.
- 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
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:bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Instale 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:
bashnpm add -D vitepress npx vitepress init
1
2Ou com Yarn:
bashyarn add -D vitepress yarn vitepress init
1
2O 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.). Opackage.json
também será atualizado com os scriptsdocs:dev
edocs:build
.
Editando o conteúdo do VitePress
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:markdown# 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.
1
2
3
4
5
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.
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:bashnpm run docs:dev -- --port 8585
1Ou com Yarn:
bashyarn docs:dev --port 8585
1O servidor estará em execução na porta especificada (por exemplo, 8585). O terminal irá mostrar o endereço local, geralmente
http://localhost:8585
.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
, comovitepress-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
parahttp://127.0.0.1:8585
.- Nome: Um identificador fácil, por exemplo
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.
Gere a versão de produção
Certifique-se de estar na raiz
/Applications/ServBay/www/servbay-vitepress-app
e rode:bashnpm run docs:build
1Ou com Yarn:
bashyarn docs:build
1O 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
.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.
- Nome: Algo que identifique como site de produção, ex:
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
:
Ative o
cleanUrls
na configuração do VitePressNo arquivo de configuração (
docs/.vitepress/config.mts
oudocs/.vitepress/config.ts
), adicione ou altere a opçãocleanUrls
:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... outras configurações cleanUrls: true, // Habilita URLs limpas // ... outras configurações })
1
2
3
4
5
6
7
8Em seguida, recompile com
npm run docs:build
.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:
bash# 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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23Salve e aplique.
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, comohttps://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.