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

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!

Configuração

The following parameters are required in docusaurus.config.js in order for Docusaurus to optimize routing and serve files from the correct location:

NomeDescrição
urlURL for your site. For a site deployed at https://my-org.com/my-project/, url is https://my-org.com/.
baseUrlBase URL for your project, with a trailing slash. For a site deployed at https://my-org.com/my-project/, baseUrl is /my-project/.

Testando localmente sua Construção

É importante testar sua construção localmente antes de implantar na produção. Docusaurus provides a docusaurus serve command for that:

npm run serve

By default, this will load your site at http://localhost:3000/.

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.

warning

In the following sections, we will introduce a few common hosting providers and how they should be configured to deploy Docusaurus sites most efficiently. The documentation may not be up-to-date: recent changes in their API may not be reflected on our side. If you see outdated content, PRs are welcome.

For the same concern of up-to-datedness, we have stopped accepting PRs adding new hosting options. You can, however, publish your writeup on a separate site (e.g. your blog, or the provider's official website), and ask us to include a link to your writeup.

Implantando no GitHub Pages

Docusaurus provides an easy way to publish to GitHub Pages, which comes for free with every GitHub repository.

Visão Geral

Usually, there are two repositories (at least, two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial they will be referred to as "source" and "deployment", respectively.

Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called my-org/my-project (where my-org is the organization name or username), the deployed site will appear at https://my-org.github.io/my-project/. Specially, if the deployment repository is called my-org/my-org.github.io (the organization GitHub Pages repo), the site will appear at https://my-org.github.io/.

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. When using a custom domain, you should be able to move back from baseUrl: '/projectName/' to baseUrl: '/', and also set your url to your custom domain.

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

GitHub Pages picks up deploy-ready files (the output from docusaurus build) from the default branch (master / main, usually) or the gh-pages branch, and either from the root or the /docs folder. You can configure that through Settings > Pages in your repository. This branch will be called the "deployment branch".

We provide a docusaurus deploy command that helps you deploy your site from the source branch to the deployment branch in one command: clone, build, and commit.

configurações docusaurus.config.js

First, modify your docusaurus.config.js and add the following params:

NomeDescrição
organizationNameThe GitHub user or organization that owns the deployment repository.
projectNameThe name of the deployment repository.
deploymentBranchThe name of deployment branch. Defaults to 'gh-pages' for non-organization GitHub Pages repos (projectName not ending in .github.io). Otherwise, this needs to be explicit as a config field or environment variable.

These fields also have their environment variable counterparts, which have a higher priority: ORGANIZATION_NAME, PROJECT_NAME, and DEPLOYMENT_BRANCH.

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

NomeDescrição
USE_SSHDefina como true para usar SSH em vez do HTTPS padrão para conexão com o repositório do GitHub. If the source repo URL is an SSH URL (e.g. [email protected]:facebook/docusaurus.git), USE_SSH is inferred to be true.
GIT_USERThe username for a GitHub account that has push access to the deployment repo. Para seus próprios repositórios, este geralmente será o seu nome de usuário do GitHub. Required if not using SSH, and ignored otherwise.
GIT_PASSPersonal access token of the git user (specified by GIT_USER), to facilitate non-interactive deployment (e.g. continuous deployment)
CURRENT_BRANCHThe source branch. Usually, the branch will be main or master, but it could be any branch except for gh-pages. If nothing is set for this variable, then the current branch from which docusaurus deploy is invoked will be used.

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
caution

Beginning in August 2021, GitHub requires every command-line sign-in to use the personal access token instead of the password. When GitHub prompts for your password, enter the PAT instead. See the GitHub documentation for more information. Alternatively, you can use SSH (USE_SSH=true) to login.

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. The workflow examples below assume your website source resides in the main branch of your repository (the source branch is main), under a folder called website/, and your publishing source is configured for the gh-pages branch (the deployment branch is gh-pages). Our goal is that:

  1. When a new pull request is made to main and updates website/, there's an action that ensures the site builds successfully, without actually deploying. This job will be called test-deploy.
  2. When a pull request is merged to the main branch or someone pushes to the main branch directly and website/ is updated, it will be built and deployed to the gh-pages branch. After that, the new built output will be served on the GitHub Pages site. This job will be called deploy. Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (gh-pages), choose the relevant tab below:
  • Source repo and deployment repo are the same repository.
  • The deployment repo is a remote repository, different from the source.

While you can have both jobs defined in the same workflow file, the deploy job will always be listed as skipped in the PR check suite status. That's added noise providing no value to the review process, and as you cannot easily share common snippets, it is better to manage them as separate workflows instead.

We will use a popular third-party deployment action: peaceiris/actions-gh-pages.

GitHub action files

Add these two workflow files:

warning

These files assume you are using yarn. If you use npm, change cache: yarn, yarn install --frozen-lockfile, yarn build to cache: npm, npm ci, npm run build accordingly.

.github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
push:
branches: [main]
paths: [website/**]

jobs:
deploy:
name: Deploy to GitHub Pages
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
with:
node-version: 14.x
cache: yarn
- name: Build website
working-directory: website
run: |
yarn install --frozen-lockfile
yarn build

# Popular action to deploy to GitHub Pages:
# Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
# Build output to publish to the `gh-pages` branch:
publish_dir: ./website/build
# Assign commit authorship to the official GH-Actions bot for deploys to `gh-pages` branch:
# https://github.com/actions/checkout/issues/13#issuecomment-724415212
# The GH actions bot is used by default if you didn't specify the two fields.
# You can swap them out with your own user credentials.
user_name: github-actions[bot]
user_email: 41898282+github-actions[bot]@users.noreply.github.com
.github/workflows/test-deploy.yml
name: Test deployment

on:
pull_request:
branches: [main]
paths: [website/**]

jobs:
test-deploy:
name: Test deployment
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
with:
node-version: 14.x
cache: yarn
- name: Test build
working-directory: website
run: |
yarn install --frozen-lockfile
yarn build

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. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the More options > Setting > Environment Variables section of your repository.
  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:
- '14.15.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 install
- 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. Add these commands in the action's terminal:
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: 14.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 install
GIT_USER="${GH_NAME}" yarn deploy
env:
GH_NAME: $(GH_NAME)
GH_EMAIL: $(GH_EMAIL)
GH_TOKEN: $(GH_TOKEN)
displayName: 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
- yarn install
- yarn deploy
environment:
USE_SSH: true
GITHUB_PRIVATE_KEY:
from_secret: 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.app', // 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. Create a project.
    • Clique em Criar projeto e dê um nome ao seu projeto.
    • Clique em Próximo.
  3. Create a new environment.
    • Clique em Criar ambiente e dar um nome (por exemplo, staging, produção).
  4. Add an application.
    • 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
  5. Deploy All you have to do now is to navigate to your application and click on Deploy.

Deploy do aplicativo

É isso. Veja o status e espere até que o aplicativo seja implantado. To open the application in your browser, click on Action and Open in your application overview.

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. Create a service.

    To deploy a Docusaurus static website, click Create in the top-left corner of your Dashboard and choose Front-end app or static website.

  2. Select the project to deploy.

    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).

    To access a different repository, click Connect another repository.

    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.

  3. Configure the build settings.

    Next, the Website customization window will appear. Choose the Static website option from the list of frameworks.

    The Directory with app points at the directory that will contain the project's files after the build. You can leave it empty if during Step 2 you selected the repository with the contents of the website (or my_website) directory.

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

    npm run build

    Se necessário, você pode modificar o comando de build. You can enter multiple commands separated by &&.

  4. Deploy.

    Click Deploy to start the build process.

    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. Usually, the log contains all the debugging data you'll need.

    When the deployment is complete, you will receive an email notification and also see a log entry. 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
  2. Para construir os arquivos estáticos do seu site para produção no diretório raiz do seu projeto, execute:
    npm run build
  3. 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
  4. Deploy your site.
    quant deploy

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