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

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_BRANCHO branch para o qual o site será publicado, padrão é gh-pages para repositórios normais e master para nomes de repositórios que terminam em github.io.
CURRENT_BRANCHA branch que contém as alterações na documentação mais recentes que serão publicadas. Geralmente, o branch será master, mas pode ser qualquer branch (padrão ou não) exceto 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 actions@github.com 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/checkout@v1      - uses: actions/setup-node@v1        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/checkout@v1      - uses: actions/setup-node@v1        with:          node-version: '12.x'      - uses: webfactory/ssh-agent@v0.5.0        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 "actions@github.com"          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_jsnode_js:  - '10'branches:  only:    - mastercache:  yarn: truescript:  - 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

Agora, sempre que um novo commit cair no master, o Travis CI vai rodar sua bateria de testes e, se tudo passar, seu site será implantado através do script yarn deploy.

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:  - master
pool:  vmImage: 'ubuntu-latest'
steps:  - checkout: self    persistCredentials: true
  - task: NodeTool@0    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 master      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.ymlkind: pipelinetype: dockertrigger:  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.

Uma vez configurado adequadamente com as opções acima, seu site deve ser implantado e reimplantado automaticamente após o merge do seu branch de implantação, que padrão é master.

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.