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:
- Instalar o ServBay: O ServBay já está instalado no seu sistema. Caso precise instalar, consulte o Guia de Instalação do ServBay.
- 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
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:
bashcd /Applications/ServBay/www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Windows:
cmdcd C:\ServBay\www mkdir servbay-vitepress-app cd servbay-vitepress-app
1
2
3Instale 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.bashnpm add -D vitepress npx vitepress init
1
2Ou com Yarn:
bashyarn add -D vitepress yarn vitepress init
1
2O 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 arquivopackage.json
também é atualizado com scripts úteis comodocs:dev
edocs:build
.
Editando o Conteúdo do Projeto VitePress
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:markdown# 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.
1
2
3
4
5
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.
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).bashnpm run docs:dev -- --port 8585
1Ou com Yarn:
bashyarn docs:dev --port 8585
1O servidor estará disponível em
http://localhost:8585
.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
parahttp://127.0.0.1:8585
.- Nome: Ex:
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.
Build da versão de produção
No terminal, diretório raiz do projeto, rode:
bashnpm run docs:build
1Ou com Yarn:
bashyarn docs:build
1Os arquivos estáticos finais são gerados em
docs/.vitepress/dist
.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
- macOS:
Salve e aplique as alterações. O ServBay vai servir os arquivos do diretório especificado pelo servidor Web.
- Nome: Ex:
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
):
Ativar
cleanUrls
no VitePressNo arquivo de configuração do VitePress (
docs/.vitepress/config.mts
oudocs/.vitepress/config.ts
), adicione ou altere:typescript// docs/.vitepress/config.mts import { defineConfig } from 'vitepress' export default defineConfig({ // ... outros configs cleanUrls: true, // Ativa URLs limpas // ... outros configs })
1
2
3
4
5
6
7
8Gere novamente a versão de produção com
npm run docs:build
.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
- macOS:
bash# 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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25Salve e finalize a configuração.
Acessar o site com URLs limpas
Agora, acesse seu domínio (ex:
https://vitepress-cleanurl.servbay.demo
). As páginas configuradas comcleanUrls
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.