9.8 KiB

Raw Permalink Blame History

outline
deep

Implante seu Site VitePress

Os guias a seguir são baseados em alguns pressupostos:

O site VitePress está dentro do diretório docs do seu projeto.
Você está usando o diretório de saída de compilação padrão (.vitepress/dist).

VitePress está instalado como uma dependência local em seu projeto, e você configurou os seguintes scripts em seu package.json:

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Compilar e Testar Localmente

Execute este comando para compilar a documentação:
```
$ npm run docs:build
```
Após a compilação, veja a prévia local executando:
```
$ npm run docs:preview
```
O comando preview inicializará um servidor web estático local que servirá o diretório de saída .vitepress/dist em http://localhost:4173. Você pode usar isso para garantir que tudo esteja correto antes de enviar para produção.
Você pode configurar a porta do servidor passando --port como argumento.
```
{
  "scripts": {
    "docs:preview": "vitepress preview docs --port 8080"
  }
}
```
Agora o método docs:preview implantará o servidor em http://localhost:8080.

Configurando um Caminho Base Público

Por padrão, assumimos que o site será implantado no caminho raiz de um domínio (/). Se seu site for servido em um subcaminho, por exemplo, https://meusite.com/blog/, você precisa então configurar a opção base para '/blog/' na configuração VitePress.

Exemplo: Ao usar GitHub Pages (ou GitLab Pages) e implantar em user.github.io/repo/, defina seu base como /repo/.

Cabeçalhos de Cache HTTP

Se você tiver controle sobre os cabeçalhos HTTP de seu servidor em produção, pode-se configurar cabeçalhos cache-control para obter melhor desempenho em visitas repetidas.

A compilação de produção usa nomes de arquivos com hash para ativos estáticos (JavaScript, CSS e outros ativos importados que não estão em public). Se você inspecionar a prévia de produção usando as ferramentas de desenvolvedor do seu nevegador na aba rede, verá arquivos como app.4f283b18.js.

Este hash 4f283b18 é gerado a partir do conteúdo deste arquivo. A mesma URL com hash é garantida para servir o mesmo conteúdo do arquivo - se o conteúdo mudar, as URLs também mudam. Isso significa que você pode usar com segurança os cabeçalhos de cache mais fortes para esses arquivos. Todos esses arquivos serão colocados em assets/ no diretório de saída, então você pode configurar o seguinte cabeçalho para eles:

Cache-Control: max-age=31536000,immutable

::: details Exemplo de arquivo _headers do Netlify

/assets/*
  cache-control: max-age=31536000
  cache-control: immutable

Nota: o arquivo _headers deve ser colocado no diretório public - em nosso caso, docs/public/_headers - para que ele seja copiado exatamente para o diretório de saída.

Documentação de cabeçalhos personalizados do Netlify

:::

::: details Exemplo de configuração Vercel em vercel.json

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Nota: o arquivo vercel.json deve ser colocado na raiz do seu repositório.

Documentação Vercel sobre configuração de cabeçalhos

:::

Guias de Plataforma

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render

Configure um novo projeto e altere estas configurações usando seu painel:

Comando de Compilação: npm run docs:build
Diretório de Saída: docs/.vitepress/dist
Versão do Node: 18 (ou superior)

::: warning Não ative opções como Auto Minify para código HTML. Isso removerá comentários da saída que têm significado para Vue. Haverão erros de incompatibilidade de hidratação se forem removidos. :::

GitHub Pages

Crie um arquivo chamado deploy.yml dentro do diretório .github/workflows do seu projeto com algum conteúdo como este:

# Exemplo de fluxo de trabalho para compilar e implantar um site VitePress no GitHub Pages
#
name: Implante o site VitePress no Pages

on:
  # Executa em pushes direcionados à branch `main`.
  # Altere para `master` se estiver usando a branch `master` como padrão.
  push:
    branches: [main]

  # Permite executar manualmente este fluxo de trabalho na guia Actions
  workflow_dispatch:

# Define permissões GITHUB_TOKEN para a implantação no GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Permite apenas uma implantação simultânea, pulando execuções em fila entre a execução em andamento e a última da fila.
# No entanto, NÃO cancela execuções em andamento, pois queremos permitir que essas implantações de produção sejam concluídas.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Trabalho de compilação
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Não necessário se lastUpdated não estiver habilitado
      # - uses: pnpm/action-setup@v3 # Descomente isso se estiver usando pnpm
      # - uses: oven-sh/setup-bun@v1 # Descomente isso se estiver usando Bun
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm # ou pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci # ou pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: |
          npm run docs:build # ou pnpm docs:build / yarn docs:build / bun run docs:build
          touch docs/.vitepress/dist/.nojekyll          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # Trabalho de implantação
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

::: warning Certifique-se de que a opção base em seu VitePress esteja configurada corretamente. Veja Configurando um Caminho Base Público para mais detalhes. :::

Nas configurações do seu repositório sob o item do menu "Pages", selecione "GitHub Actions" em "Build and deployment > Source".
Envie suas alterações para a branch main e aguarde a conclusão do fluxo de trabalho do GitHub Actions. Você verá seu site implantado em https://<username>.github.io/[repository]/ ou https://<custom-domain>/ dependendo das suas configurações. Seu site será implantado automaticamente em cada push para a branch main.

GitLab Pages

Defina outDir na configuração VitePress como ../public. Configure a opção base para '/<repository>/' se você deseja implantar em https://<username>.gitlab.io/<repository>/.

Crie um arquivo chamado .gitlab-ci.yml na raiz do seu projeto com o conteúdo abaixo. Isso construirá e implantará seu site sempre que você fizer alterações no conteúdo:

image: node:18
pages:
  cache:
    paths:
      - node_modules/
  script:
    # - apk add git # Descomente isso se estiver usando imagens pequenas do Docker como o Alpine e tiver lastUpdated habilitado
    - npm install
    - npm run docs:build
  artifacts:
    paths:
      - public
  only:
    - main

Azure Static Web Apps

Siga a documentação oficial.
Configure esses valores em seu arquivo de configuração (e remova aqueles que você não precisa, como api_location):
- app_location: /
- output_location: docs/.vitepress/dist
- app_build_command: npm run docs:build

Firebase

Crie firebase.json e .firebaserc na raiz do seu projeto:

firebase.json:

{
  "hosting": {
    "public": "docs/.vitepress/dist",
    "ignore": []
  }
}

.firebaserc:

{
  "projects": {
    "default": "<SEU_ID_FIREBASE>"
  }
}

Após executar npm run docs:build, execute este comando para implantar:
```
firebase deploy
```

Surge

Após executar npm run docs:build, execute este comando para implantar:
```
npx surge docs/.vitepress/dist
```

Heroku

Siga a documentação e o guia fornecidos em heroku-buildpack-static.
Crie um arquivo chamado static.json na raiz do seu projeto com o conteúdo abaixo:
```
{
  "root": "docs/.vitepress/dist"
}
```

Edgio

Consulte Criar e Implantar um Aplicativo VitePress no Edgio.

Kinsta Static Site Hosting

Você pode implantar seu site VitePress em Kinsta seguindo estas instruções.

9.8 KiB Raw Permalink Blame History