Ir para o conteúdo principal
Version: 2.0.0-beta.8

Deployment

Para construir os arquivos estáticos do seu site para produção, execute:

npm run build

Quando terminar, os arquivos estáticos serão gerados dentro do diretório build.

note

A única responsabilidade do Docusaurus é construir seu site e emitir arquivos estáticos na build.

Agora cabe a você escolher como hospedar esses arquivos estáticos.

Você pode fazer o deploy do seu site para serviços estáticos de hospedagem como Vercel, GitHub Pages, Netlify, Render, Surge...

Um site Docusaurus é renderizado estaticamente e geralmente pode funcionar sem JavaScript!

Testando localmente sua Construção

É importante testar sua construção localmente antes de implantar na produção.

Docusaurus inclui um comando docusaurus serve para isso:

npm run serve

Configuração de barra

Docusaurus tem uma configuraçãotrailingSlash, para permitir a personalização de URLs/links e padrões de nomes de arquivos emitidos.

O valor padrão geralmente funciona bem.

Infelizmente, cada provedor de hospedagem estática tem um comportamento diferente e implantar exatamente o mesmo site em vários hosts pode levar a resultados distintos.

Dependendo do seu host, pode ser útil alterar essa configuração.

tip

Use slorber/trailing-slash-guide para entender melhor o comportamento do seu host e configurar trailingSlash adequadamente.

Auto-hospedado

O Docusaurus pode ser auto-hospedado usando docusaurus serve. Muda a porta usando --port e --host para alterar o host.

npm run serve -- --build --port 80 --host 0.0.0.0
warning

Não é a melhor opção, em comparação com um provedor de hospedagem estática / CDN.

Implantando no GitHub Pages

O Docusaurus fornece uma maneira fácil de publicar no GitHub Pages. Que é a hospedagem que vem de graça com todos os repositórios do GitHub.

configurações docusaurus.config.js

Primeiro, modifique seu docusaurus.config.js e adicione os parâmetros necessários:

NomeDescrição
organizationNameO usuário ou organização proprietária do repositório. Se você é o proprietário, é o seu nome de usuário do GitHub. No caso do Docusaurus, é "Facebook" que é a organização do Docusaurus.
projectNameO nome do repositório do GitHub. Por exemplo, o nome do repositório para o Docusaurus é "docusaurus", então o nome do projeto é "docusaurus".
urlURL para a página de usuário/organização da sua página do GitHub. Isso geralmente é https://_username_.github.io.
baseUrlURL base para o seu projeto. Para projetos hospedados nas páginas do GitHub, segue o formato "/projectName/". Para https://github.com/facebook/docusaurus, baseUrl é /docusaurus/.
info

Caso você queira usar seu domínio personalizado no GitHub Pages, crie um arquivo CNAME no diretório static. Qualquer coisa dentro do diretório static será copiada para a raiz do diretório build para fazer o deploy.

Ao usar um domínio personalizado, você deve ser capaz de voltar de baseUrl: '/projectName/' para baseUrl: '/'

Você pode consultar a documentação Usuário, Organização e Páginas do Projeto das Páginas do GitHub para mais detalhes.

caution

O GitHub Pages adiciona uma barra à direita nas URLs do Docusaurus por padrão. É recomendável definir uma configuração do trailingSlash (true ou false, e não undefined).

Exemplo:

docusaurus.config.js
module.exports = {
// ...
url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/',
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// ...
};
warning

Por padrão, o GitHub Pages executa arquivos publicados através do Jekyll. Como o Jekyll descartará todos os arquivos que começam com _, é recomendado que você desative o Jekyll adicionando um arquivo vazio chamado .nojekyll no seu diretório static.

Configurações de ambiente

Especifique o usuário Git como uma variável de ambiente.

NomeDescrição
GIT_USERO nome de usuário de uma conta do GitHub que tenha acesso a este repositório. Para seus próprios repositórios, este geralmente será o seu nome de usuário do GitHub. O GIT_USER especificado deve ter acesso push ao repositório especificado na combinação de organizationName e projectName.

Parâmetros opcionais, também definir como variáveis de ambiente:

NomeDescrição
USE_SSHDefina como true para usar SSH em vez do HTTPS padrão para conexão com o repositório do GitHub.
DEPLOYMENT_BRANCHThe branch that the website will be deployed to, defaults to gh-pages. For GitHub Pages Organization repos (config.projectName ending in github.io), this env variable is required.
CURRENT_BRANCHA branch que contém as alterações na documentação mais recentes que serão publicadas. Usually, the branch will be main, but it could be any branch (default or otherwise) except for gh-pages. Se nada for definido para essa variável, então a branch atual será usado.
GIT_PASSSenha (ou token) do usuário git (especificado por GIT_USER). Por exemplo, para facilitar a implantação não-interativa (ex: continuous deployment)

As instalações corporativas do GitHub devem funcionar da mesma maneira que o github.com; você só precisa definir o host GitHub Enterprise da organização como uma variável de ambiente:

NomeDescrição
GITHUB_HOSTO nome de domínio do seu site corporativo GitHub.
GITHUB_PORTA porta do seu site corporativo GitHub.

Deploy

Finalmente, para fazer o deploy do seu site no GitHub Pages, execute:

GIT_USER=<GITHUB_USERNAME> yarn deploy

Desencadeando deploy com GitHub Actions

GitHub Actions permite que você autentique, personalize e execute seus fluxos de trabalho de desenvolvimento de software diretamente no seu repositório. Esse fluxo de trabalho assume que a sua documentação está no branch documentation do repositório e que a fonte de publicação está configurada para o branch gh-pages.

  1. Gerar uma nova chave SSH.
  2. Por padrão, sua chave pública deve ter sido criada em ~/.ssh/id_rsa. ub ou use o nome que você forneceu no passo anterior para adicionar sua chave a chaves de deploy do GitHub.
  3. Copie a chave para a área de transferência com xclip -sel clip < ~/.ssh/id_rsa.pub e cole-o como uma chave de deploy no seu repositório. Copie o conteúdo do arquivo se o comando não funcionar para você. Marque a caixa para Allow write access antes de salvar sua chave de deploy.
  4. Você precisará da sua chave privada como um GitHub secret para permitir que o Docusaurus execute o deploy para você.
  5. Copie sua chave privada com xclip -sel clip < ~/.ssh/id_rsa e cole um segredo do GitHub com o nome GH_PAGES_DEPLOY. Copie o conteúdo do arquivo se o comando não funcionar para você. Salve sua senha.
  6. Crie o seu arquivo de workflow da documentação em .github/workflows/. Neste exemplo, é documentation.yml.
    warning

    Certifique-se de substituir as [email protected] pelo seu e-mail no GitHub e gh-actions pelo seu nome.

documentation.yml
name: documentation

on:
pull_request:
branches: [documentation]
push:
branches: [documentation]

jobs:
checks:
if: github.event_name != 'push'
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
with:
node-version: '12.x'
- name: Test Build
run: |
if [ -e yarn.lock ]; then
yarn install --frozen-lockfile
elif [ -e package-lock.json ]; then
npm ci
else
npm i
fi
npm run build
gh-release:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
with:
node-version: '12.x'
- uses: webfactory/ssh-[email protected]
with:
ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
- name: Release to GitHub Pages
env:
USE_SSH: true
GIT_USER: git
run: |
git config --global user.email "[email protected]"
git config --global user.name "gh-actions"
if [ -e yarn.lock ]; then
yarn install --frozen-lockfile
elif [ -e package-lock.json ]; then
npm ci
else
npm i
fi
npm run deploy
  1. Agora, quando um novo pull request chegar no seu repositório no branch documentation, ela irá automaticamente garantir que a construção do Docusaurus seja bem-sucedida.
  2. Quando o pull request for mesclado ao branch documentation ou se alguém fizer push no branch documentation diretamente ele será construído e feito deploy no branch gh-pages.
  3. Depois deste passo, a sua documentação atualizada estará disponível no GitHub pages.

Desencadeando deploy com Travis CI

Serviços de integração contínua (CI) são normalmente usados para executar tarefas de rotina sempre que novos commits são enviados para o controle de código fonte. Estas tarefas podem ser qualquer combinação de testes unitários e de integração, automatizando compilações, publicando pacotes ao NPM e implantando alterações em seu site. Tudo o que você precisa fazer para automatizar o deploy do seu site é invocar o script yarn deploy sempre que seu site é atualizado. A seção a seguir cobre como fazer exatamente isso usando o Travis CI, um popular provedor de serviços de integração contínua.

  1. Vá para https://github.com/settings/tokens e gere um novo token de acesso pessoal. Ao criar o token, conceda o escopo do repositório para que ele tenha as permissões de que precisa.
  2. Usando sua conta do GitHub, adicione o aplicativo Travis CI ao repositório que você deseja ativar.
  3. Abra seu painel do Travis CI. A URL se parece com https://travis-ci. om/USERNAME/REPO, e navegue até a seção Mais opções > Configurando > Variáveis de ambiente do seu repositório.
  4. Crie uma nova variável de ambiente chamada GH_TOKEN com seu token recém-gerado como seu valor, em seguida GH_EMAIL (seu endereço de e-mail) e GH_NAME (seu nome de usuário GitHub).
  5. Crie um .travis.yml na raiz do seu repositório com o seguinte:
.travis.yml
language: node_js
node_js:
- '12.13.0'
branches:
only:
- main
cache:
yarn: true
script:
- git config --global user.name "${GH_NAME}"
- git config --global user.email "${GH_EMAIL}"
- echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
- yarn && GIT_USER="${GH_NAME}" yarn deploy

Now, whenever a new commit lands in main, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the yarn deploy script.

Desencadeando deploy com o Buddy

Buddy é uma ferramenta de CI/CD fácil de usar que permite automatizar o deploy do seu portal para diferentes ambientes, incluindo GitHub Pages.

Siga estas etapas para criar um pipeline que implanta automaticamente uma nova versão do seu site sempre que você fizer push de alterações no branch selecionado do seu projeto:

  1. Vá para https://github.com/settings/tokens e gere um novo token de acesso pessoal. Ao criar o token, conceda o escopo do repositório para que ele tenha as permissões de que precisa.
  2. Acesse sua conta do Buddy e crie um novo projeto.
  3. Escolha o GitHub como seu provedor de hospedagem git e selecione o repositório com o código do seu site.
  4. Usando o painel de navegação da esquerda, mude para a exibição de pipelines.
  5. Crie uma nova pipeline. Defina o seu nome, defina o modo de trigger como On push, e selecione o branch que aciona a execução do pipeline.
  6. Adicione uma ação Node.js.
  7. Adicione este comando no terminal da ação:
    GIT_USER=<GH_PERSONAL_ACCESS_TOKEN>
    git config --global user.email "<YOUR_GH_EMAIL>"
    git config --global user.name "<YOUR_GH_USERNAME>"
    yarn deploy

Depois de criar este pipeline simples, cada novo commit enviado para o branch que você selecionou implementa seu site para o GitHub Pages usando yarn deploy. Leia este guia para aprender mais sobre como criar um pipeline de CI/CD para o Docusaurus.

Usando Pipelines da Azure

  1. Cadastre-se em Azure Pipelines se você ainda não o fez.
  2. Crie uma organização e dentro da organização e crie um projeto e conecte seu repositório a partir do GitHub.
  3. Vá para https://github.com/settings/tokens e gere um novo token de acesso pessoal com o escopo repositório.
  4. Na página do projeto (que se parece com https://dev.azure.com/ORG_NAME/REPO_NAME/_build crie um novo pipeline com o texto a seguir. Além disso, clique em editar e adicione uma nova variável de ambiente chamada GH_TOKEN com seu token recém-gerado como seu valor, em seguida GH_EMAIL (seu endereço de e-mail) e GH_NAME (seu nome de usuário GitHub). Certifique-se de marcá-los como secretos. Como alternativa, você também pode adicionar um arquivo chamado azure-pipelines.yml na sua raiz do repositório.
azure-pipelines.yml
trigger:
- main

pool:
vmImage: 'ubuntu-latest'

steps:
- checkout: self
persistCredentials: true

- task: [email protected]
inputs:
versionSpec: '10.x'
displayName: 'Install Node.js'

- script: |
git config --global user.name "${GH_NAME}"
git config --global user.email "${GH_EMAIL}"
git checkout -b main
echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
yarn && GIT_USER="${GH_NAME}" yarn deploy
env:
GH_NAME: $(GH_NAME)
GH_EMAIL: $(GH_EMAIL)
GH_TOKEN: $(GH_TOKEN)
displayName: 'yarn install and build'

Usando o Drone

  1. Crie uma nova chave ssh que será a chave de deploy para o seu projeto.
  2. Nomeie suas chaves privadas e públicas para serem específicas e para que não substitua suas outras chaves ssh.
  3. Vá para https://github.com/USERNAME/REPO/settings/keys e adicione uma nova chave de deploy colando nossa chave pública que você acabou de gerar.
  4. Abra o seu painel do Drone.io e faça login. O URL se parece com https://cloud.drone.io/USERNAME/REPO.
  5. Clique no repositório, clique em ativar repositório e adicione um segredo chamado git_deploy_private_key com o valor da sua chave privada que você acabou de gerar.
  6. Crie um .drone.yml na raiz do seu repositório com o texto abaixo.
# .drone.yml
kind: pipeline
type: docker
trigger:
event:
- tag
- name: Website
image: node
commands:
- mkdir -p $HOME/.ssh
- ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
- echo "$GITHUB_PRIVATE_KEY > $HOME/.ssh/id_rsa"
- chmod 0600 $HOME/.ssh/id_rsa
- cd website
- npm i
- npm run publish-gh-pages
environment:
USE_SSH: true
GIT_USER: $DRONE_COMMIT_AUTHOR
GITHUB_PRIVATE_KEY: git_deploy_private_key

Agora, sempre que você enviar uma nova tag para o github, esta opção começará o trabalho do drone para publicar seu site.

Fazendo deploy no Netlify

Para publicar seus sites Docusaurus 2 no Netlify, primeiro certifique-se de que as seguintes opções estão configuradas corretamente:

docusaurus.config.js
module.exports = {
url: 'https://docusaurus-2.netlify.com', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
// ...
};

Em seguida, crie o seu site com Netlify.

Enquanto você configura o site, especifique os comandos de compilação e os diretórios da seguinte forma:

  • comando de construção: npm run build
  • diretório compilação: build

Se você não configurou essas opções de compilação, ainda poderá ir para "Configurações do Site" -> "Construir e implantar" depois que seu site for criado.

Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to main.

caution

Some Docusaurus sites put the docs folder outside of website (most likely former Docusaurus v1 sites):

repo           # git root
├── docs # md files
└── website # docusaurus root

If you decide to use the website folder as Netlify's base directory, Netlify will not trigger builds when you update the docs folder, and you need to configure a custom ignore command:

website/netlify.toml
[build]
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"
warning

Por padrão, o Netlify adiciona barras de rastreamento às URLs do Docusaurus.

É recomendável desativar a configuração Netlify Pós-Processamento > Otimização de ativos > URLs Pretty para evitar URLs minúsculas, redirecionamentos desnecessários e erros 404.

Tenha muito cuidado: a caixa de seleção global Desativar otimização de ativos está quebrada e realmente não desativa a configuração de Pretty URLs na prática. Certifique-se de desmarcá-lo manualmente.

Se você quer manter as Pretty Urls Netlify configurado, ajuste adequadamente a trailingSlash configuração do Docusaurus.

Consulte slorber/trailing-slash-guide para obter mais informações.

Publicando no Vercel

Fazer o deploy do seu projeto Docusaurus no Vercel irá proporcionar vários benefícios nas áreas de desempenho e facilidade de uso.

Para implantar seu projeto Docusaurus com um Vercel para Integração Git, certifique-se de que ele tenha sido enviado para um repositório Git.

Importe o projeto para Vercel utilizando o Import Flow. Durante a importação, você encontrará todas as opções relevantes pré-configuradas para você; no entanto, você pode optar por alterar qualquer uma dessas opções, uma lista das quais pode ser encontrada aqui.

Depois que o seu projeto for importado, todos os pushes subsequentes em branches gerarão Pré-visualizar deploys, e todas as alterações feitas no branch de produção (comumente "principal") resultarão em uma implantação de produção.

Publicando no Render

Render oferece hospedagem estática gratuita com SSL totalmente gerenciado, domínios personalizados, um CDN global e um deploy automático contínuo a partir do seu repositório Git. Comece em apenas alguns minutos seguindo o guia do Render para publicar o Docusaurus.

Publicando no Qovery

Qovery é uma plataforma de nuvem totalmente gerenciada que é executada em sua AWS, Digital Ocean e Scaleway onde você pode hospedar sites estáticos, APIs de backend, bancos de dados, cron e todos os seus outros aplicativos em um só lugar.

  1. Cria uma conta no Qovery. Visite o Painel Qovery para criar uma conta, caso você ainda não tenha uma.

  2. Crie um projeto

  • Clique em Criar projeto e dê um nome ao seu projeto.
  • Clique em Próximo.
  1. Criar um novo ambiente
  • Clique em Criar ambiente e dar um nome (por exemplo, staging, produção).
  1. Adicionar um aplicativo
  • Clique em Criar um aplicativo, dê um nome e selecione seu repositório GitHub ou GitLab onde seu aplicativo Docusaurus está localizado.
  • Define o nome da ramificação principal e o caminho da aplicação raiz.
  • Clique em Criar.

Depois que o aplicativo for criado:

  • Navegue para Configurações da sua aplicação
  • Selecione Porta
  • Adicionar a porta usada pelo aplicativo Docusaurus
  1. Deploy All o que você precisa fazer agora é navegar até seu aplicativo e clicar em Deploy

Deploy do aplicativo

É isso. Veja o status e espere até que o aplicativo seja implantado.

Para abrir o aplicativo no seu navegador, clique em Ação e Abrir na visão geral do aplicativo

Publicando no Hostman

Hostman permite que você hospede sites estáticos gratuitamente. O Hostman automatica tudo, você só precisa conectar seu repositório e seguir etapas simples:

  1. Crie um serviço

Para implantar um site estático do Docusaurus, clique em Criar no canto superior esquerdo do Painel e escolha app Front-end ou site estático.

  1. Selecione o projeto para publicar

Se você estiver conectado ao Hostman com sua conta GitHub, GitLab ou Bitbucket, Nesse momento, você verá o repositório com seus projetos, incluindo os privados.

Escolha o projeto que deseja publicar. Ele deve conter o diretório com os arquivos do projeto (geralmente é site ou minha-site).

Para acessar um repositório diferente, clique em Conectar outro repositório.

Se você não usou as credenciais de sua conta do Git para logar, poderá acessar a conta necessária agora e então selecionar o projeto.

  1. Configure as configurações de construção em seguida, a janela de personalização do site aparecerá.

Escolha a opção do site Estático na lista de frameworks.

O Diretório com pontos do aplicativo no diretório que conterá os arquivos do projeto após a compilação. Você pode deixá-lo em branco se durante a Etapa 2 você selecionou o repositório com o conteúdo do diretório do site (ou meu_site).

O comando padrão de construção do Docusaurus será:

yarn run build

Se necessário, você pode modificar o comando de build. Você pode inserir vários comandos separados por &&.

  1. Implantar clique em deploy para iniciar o processo de construção.

Quando começar, você vai digitar o log de implantação. Se houver quaisquer problemas com o código, você receberá mensagens de aviso ou erro no log, especificando a causa do problema.

Geralmente, o log contém todos os dados de depuração que você precisará. mas também estamos aqui para o ajudar a resolver as questões, por isso não hesitem em contactar-nos através do chat.

Quando a implantação estiver concluída, você receberá uma notificação por e-mail e também verá uma entrada de log.

Tudo pronto!

Seu projeto está pronto.

Publicando no Surge

Surge é uma plataforma estática de hospedagem de web, ela é usada para implantar seu projeto Docusaurus na linha de comando em um minuto. Fazer deploy do seu projeto no Surge é fácil e também é gratuito (incluindo um domínio personalizado e SSL).

Coloque seu aplicativo em questão de segundos usando surge com os seguintes passos:

  1. Primeiro, instale o Surge usando o npm executando o seguinte comando:
npm install --g surge
  1. Para construir os arquivos estáticos do seu site para produção no diretório raiz do seu projeto, execute:
npm run build
  1. Em seguida, execute esse comando dentro do diretório raiz do seu projeto:
surge build/

Primeiros usuários do Surge seriam convidados a criar uma conta a partir da linha de comando (acontece apenas uma vez).

Confirme que o site que você deseja publicar está no diretório build, um subdomínio gerado aleatoriamente *.surge.sh subdomain é sempre informado (que pode ser editado).

Usando seu domínio

Se você tem um nome de domínio, você pode implantar seu site usando o comando surge em seu domínio:

surge build/ yourdomain.com

Seu site agora é gratuitamente implantado em subdomain.surge.sh ou yourdomain.com dependendo do método que você escolheu.

Configurando o arquivo CNAME

Armazene seu domínio em um arquivo CNAME para futuras implantações com o seguinte comando:

echo subdomain.surge.sh > CNAME

Você pode implantar quaisquer outras alterações no futuro com o comando surge.

Publicando no QuantCDN

  1. Instale o Quant CLI

  2. Crie uma conta QuantCDN através do signing up

  3. Inicialize o seu projeto com init e preencha suas credenciais:

quant init
  1. Deploy do seu site
quant deploy

Consulte a documentação e o blog para mais exemplos e use casos para publicar no QuantCDN.