From 1cb4c7cf2c0b5183ca482f7409889f01b830e0d0 Mon Sep 17 00:00:00 2001 From: Vinicius de Liz Date: Thu, 1 Feb 2024 14:01:15 -0300 Subject: [PATCH] i18n(pt): Create and translate `docs/pt/guide/deploy.md` --- docs/pt/guide/deploy.md | 291 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 docs/pt/guide/deploy.md diff --git a/docs/pt/guide/deploy.md b/docs/pt/guide/deploy.md new file mode 100644 index 00000000..aeba4b3d --- /dev/null +++ b/docs/pt/guide/deploy.md @@ -0,0 +1,291 @@ +--- +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`: + + ```json + { + "scripts": { + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" + } + } + ``` + +## Compilar e Testar Localmente + +1. Execute este comando para compilar a documentação: + + ```sh + $ npm run docs:build + ``` + +2. Após a compilação, veja a prévia local executando: + + ```sh + $ 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. + +3. Você pode configurar a porta do servidor passando `--port` como argumento. + + ```json + { + "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`](../reference/site-config#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](./asset-handling#the-public-directory) - 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](https://docs.netlify.com/routing/headers/) + +::: + +::: details Exemplo de configuração Vercel em `vercel.json` + +```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](https://vercel.com/docs/concepts/projects/project-configuration#headers) + +::: + +## 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 + +1. Crie um arquivo chamado `deploy.yml` dentro do diretório `.github/workflows` do seu projeto com algum conteúdo como este: + + ```yaml + # 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@v2 # 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](#setting-a-public-base-path) para mais detalhes. + ::: + +2. Nas configurações do seu repositório sob o item do menu "Pages", selecione "GitHub Actions" em "Build and deployment > Source". + +3. 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://.github.io/[repository]/` ou `https:///` dependendo das suas configurações. Seu site será implantado automaticamente em cada push para a branch `main`. + +### GitLab Pages + +1. Defina `outDir` na configuração VitePress como `../public`. Configure a opção `base` para `'//'` se você deseja implantar em `https://.gitlab.io//`. + +2. 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: + + ```yaml + 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 + +1. Siga a [documentação oficial](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration). + +2. 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 + +1. Crie `firebase.json` e `.firebaserc` na raiz do seu projeto: + + `firebase.json`: + + ```json + { + "hosting": { + "public": "docs/.vitepress/dist", + "ignore": [] + } + } + ``` + + `.firebaserc`: + + ```json + { + "projects": { + "default": "" + } + } + ``` + +2. Após executar `npm run docs:build`, execute este comando para implantar: + + ```sh + firebase deploy + ``` + +### Surge + +1. Após executar `npm run docs:build`, execute este comando para implantar: + + ```sh + npx surge docs/.vitepress/dist + ``` + +### Heroku + +1. Siga a documentação e o guia fornecidos em [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). + +2. Crie um arquivo chamado `static.json` na raiz do seu projeto com o conteúdo abaixo: + + ```json + { + "root": "docs/.vitepress/dist" + } + ``` + +### Edgio + +Consulte [Criar e Implantar um Aplicativo VitePress no Edgio](https://docs.edg.io/guides/vitepress). + +### Kinsta Static Site Hosting + +Você pode implantar seu site Vitepress em [Kinsta](https://kinsta.com/static-site-hosting/) seguindo estas [instruções](https://kinsta.com/docs/vitepress-static-site-example/).