Publishing your site · Docusaurus

Agora você já deve ter um site pronto rodando localmente. Assim que você tiver terminado de personalizar ele para ficar nos trinques, é hora de publicá-lo. O Docusaurus gera um site estático HTML prontinho para ser servido pelo seu servidor ou solução de hospedagem favorito.

Gerando páginas estáticas HTML

Para criar uma versão estática do seu site, execute o seguinte script no diretório website:

yarn run build # ou `npm run build`

Isso vai gerar um diretório build dentro do diretório website contendo os arquivos .html da sua documentação e de outras páginas incluídas em pages.

Hospedando páginas estáticas HTML

Neste ponto, você já pode pegar todos os arquivos dentro do diretório website/build e copiar eles diretamente para o diretório html do seu servidor web favorito.

For example, both Apache and Nginx serve content from /var/www/html by default. Com isso dito, escolher onde você vai hospedar seu site está fora do escopo do Docusaurus.

Ao servir o site a partir de seu próprio servidor web, certifique-se de que ele esteja servindo os arquivos de assets com os cabeçalhos HTTP adequados. Arquivos CSS devem ser servidos com o cabeçalho de content-type como text/css. In the case of Nginx, this would mean setting include /etc/nginx/mime.types; in your nginx.conf file. See this issue for more info.

Using ZEIT Now

Deploying your Docusaurus project to ZEIT Now will provide you with various benefits in the areas of performance and ease of use.

O mais importante, entretanto, implantar um projeto Docusaurus leva apenas alguns segundos:

First, install their command-line interface:

npm i -g now

Run a single command inside the root directory of your project:

now

That's all. Your docs will automatically be deployed.

Usando o GitHub Pages

Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: GitHub Pages.

Deploying to GitHub Pages

Docusaurus supports deploying as project pages or user/organization pages, your code repository does not even need to be public.

Mesmo que seu repositório seja privado, qualquer coisa publicada em uma branch gh-pages será pública.

Note: When you deploy as user/organization page, the publish script will deploy these sites to the root of the master branch of the username.github.io repo. Nesse caso, observe que você vai querer ter a infraestrutura do Docusaurus, sua documentação, etc. either in another branch of the username.github.io repo (e.g., maybe call it source), or in another, separate repo (e.g. in the same as the documented source code).

You will need to modify the file website/siteConfig.js and add the required parameters.

Nome	Descrição
`organizationName`	O usuário ou organização que é dona do repositório. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "facebook" GitHub organization.
`projectName`	O nome do repositório do seu projeto no GitHub. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus".
`url`	Your website's URL. For projects hosted on GitHub pages, this will be "https://username.github.io"
`baseUrl`	Base URL for your project. For projects hosted on GitHub pages, it follows the format "/projectName/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`.

const siteConfig = {
  ...
  url: 'https://__userName__.github.io', // Your website URL
  baseUrl: '/testProject/',
  projectName: 'testProject',
  organizationName: 'userName'
  ...
}

In case you want to deploy as a user or organization site, specify the project name as <username>.github.io or <orgname>.github.io. E.g. If your GitHub username is "user42" then user42.github.io, or in the case of an organization name of "org123", it will be org123.github.io.

Note: Not setting the url and baseUrl of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.

Por mais que recomendemos configurar o projectName e o organizationName no siteConfig.js, você também pode usar as variáveis de ambiente ORGANIZATION_NAME e PROJECT_NAME.

Now you have to specify the git user as an environment variable, and run the script publish-gh-pages

Nome	Descrição
`GIT_USER`	O nome de usuário de uma conta do GitHub que tenha permissão para fazer commits para este repositório. No caso dos seus próprios repositórios, você pode usar seu próprio nome de usuário do GitHub. O `GIT_USER` especificado precisa ter acesso de push no repositório especificado pela combinação de `organizationName` e `projectName`.

Para rodar o script diretamente da linha de comando, você pode usar o seguinte comando, preenchendo os valores de parâmetros conforme apropriado.

GIT_USER=<GIT_USER> \
  CURRENT_BRANCH=master \
  USE_SSH=true \
  yarn run publish-gh-pages # ou `npm run publish-gh-pages`

Há também dois parâmetros opcionais que são definidos como variáveis de ambiente:

Nome	Descrição
`USE_SSH`	Se definida como `true`, a conexão ao repositório do GitHub será feita por meio de SSH, ao invés de HTTPS. HTTPS é o padrão se essa variável não for definida.
`CURRENT_BRANCH`	A branch que contém as alterações na documentação mais recentes que serão publicadas. Geralmente, essa branch será a `master`, mas poderia ser qualquer branch (padrão ou não) exceto pela `gh-pages`. Se nada for definido para essa variável, então a branch atual será usada.

Caso enfrente problemas relacionados a chaves SSH, visite a documentação de autenticação do GitHub.

Agora você já deve ser capaz de abrir seu site visitando o URL dele no GitHub Pages, o qual deve ser algo como https://nome-de-usuario.github.io/projectName, ou um domínio personalizado, caso você tenha configurado assim. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus because it is served from the gh-pages branch of the https://github.com/facebook/docusaurus GitHub repository. However, it can also be accessed via https://docusaurus.io/, via a generated CNAME file which can be configured via the cname siteConfig option.

Recomendamos fortemente que você leia a documentação do GitHub Pages para saber mais sobre como essa solução de hospedagem funciona.

Você pode executar o comando acima a qualquer momento que você atualizar sua documentação e desejar publicar as alterações no seu site. Executar o script manualmente pode funcionar bem para sites onde a documentação raramente muda e não seja muito inconveniente lembrar de publicar as alterações manualmente.

No entanto, você pode automatizar o processo de publicação com integração contínua (CI).

Automatizando deploys usando integração contínua

Serviços de integração contínua (CI) são normalmente usados para realizar tarefas de rotina sempre que novos commits são enviados para o controle de código fonte. Dentre essas tarefas estão a execução de testes unitários e de integração, a automatização de builds, a publicação de pacotes ao NPM e, sim, a implementação de alterações ao seu site. Tudo o que você precisa fazer para automatizar os deploys do seu site é invocar o script publish-gh-pages sempre que sua documentação for atualizada. In the following section, we'll be covering how to do just that using CircleCI, a popular continuous integration service provider.

Usando CircleCI 2.0

Se ainda não tiver o feito, você pode configurar o CircleCI para seu projeto de código aberto. Depois disso, para poder fazer o deploy automático do seu site e documentação via CircleCI, basta configurar o Circle para executar o script publish-gh-pages como parte do processo de deploy. Você pode seguir este passo-a-passo para configurar certinho:

Tenha certeza que a conta do GitHub que vai ser definida como GIT_USER tem acesso de escrita (write) ao repositório que contém a documentação. Você pode ver isso em Settings | Collaborators & teams no repositório.
Faça login no GitHub como o GIT_USER.
Vá para https://github.com/settings/tokens como o GIT_USER e gere um novo token de acesso pessoal, concedendo a ele controle total sobre repositórios privados através do escopo de acesso repository. Guarde este token em um lugar seguro, e tenha certeza de não compartilhar ele com ninguém. Este token pode ser usado para autenticar e realizar ações em seu nome, como se fosse a sua senha do GitHub.
Open your CircleCI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". O URL é algo como https://circleci.com/gh/ORG/REPO/edit#env-vars, onde "ORG/REPO" deve ser substituído pela sua própria organização/repositório do seu GitHub.
Crie uma nova variável de ambiente chamada GITHUB_TOKEN, usando seu token de acesso recém-criado como o valor dela.
Crie um diretório .circleci e crie um arquivo config.yml dentro dele.
Copie o texto abaixo para o .circleci/config.yml.

# Se você quiser que o Circle entre em ação apenas em commits diretos à master,
# você pode descomentar as linhas seguintes e também o filtro `*filter-only-master`
# lá no fim do arquivo
#
# aliases:
#  - &filter-only-master
#    branches:
#      only:
#        - master

version: 2
jobs:
  deploy-website:
    docker:
      # Especifique aqui a versão desejada

      - image: circleci/node:8.11.1

    steps:

      - checkout
      - run:
          name: Fazendo deploy no GitHub Pages
          command: |
            git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
            git config --global user.name "<YOUR_NAME>"
            echo "machine github.com login <GITHUB_USERNAME> password $GITHUB_TOKEN" > ~/.netrc
            cd website && yarn install && GIT_USER=<GIT_USER> yarn run publish-gh-pages

workflows:
  version: 2
  build_and_deploy:
    jobs:

      - deploy-website:
#         filters: *filter-only-master

Não se esqueça de substituir todos os <....> na sequência command: com os valores adequados. Como <GIT_USER>, você pode definir uma conta do GitHub que tenha permissão de push na documentação do seu repositório do GitHub. Na maioria das vezes, <GIT_USER> e <GITHUB_USERNAME> serão a mesma coisa.

NÃO coloque o valor da variável $GITHUB_TOKEN no circle.yml. We already configured that as an environment variable back in Step 5.

Se você quiser usar SSH para a conexão com o seu repositório GitHub, você pode configurar USE_SSH=true. Dessa forma, o comando acima seria algo como: cd website && npm install && GIT_USER=<GIT_USER> USE_SSH=true npm run publish-gh-pages.

Unlike when you run the publish-gh-pages script manually when the script runs within the Circle environment, the value of CURRENT_BRANCH is already defined as an environment variable within CircleCI and will be picked up by the script automatically.

Agora, sempre que um novo commit pintar na branch master, o CircleCI vai rodar sua bateria de testes e, se tudo passar, seu site será publicado através do script publish-gh-pages.

If you would rather use a deploy key instead of a personal access token, you can by starting with the CircleCI instructions for adding a read/write deploy key.

Truques e dicas

When initially deploying to a gh-pages branch using CircleCI, you may notice that some jobs triggered by commits to the gh-pages branch fail to run successfully due to a lack of tests (This can also result in chat/slack build failure notifications).

You can work around this by:

Setting the environment variable CUSTOM_COMMIT_MESSAGE flag to the publish-gh-pages command with the contents of [skip ci]. e.g.

CUSTOM_COMMIT_MESSAGE="[skip ci]" \
  yarn run publish-gh-pages # or `npm run publish-gh-pages`

Alternatively, you can work around this by creating a basic CircleCI config with the following contents:

# CircleCI 2.0 Config File
# This config file will prevent tests from being run on the gh-pages branch.
version: 2
jobs:
  build:
    machine: true
    branches:
      ignore: gh-pages
    steps:
      - run: echo "Pulando testes na branch gh-pages"

Salve este arquivo como config.yml e coloque-o em um diretório .circleci dentro do seu diretório website/static.

Usando o Travis CI

Vá para https://github.com/settings/tokens e gere um novo token de acesso pessoal
Usando sua conta do GitHub, adicione o app Travis CI ao repositório que você deseja ativar.
Abra seu painel do Travis CI. O URL é algo como https://travis-ci.com/NOME_USUARIO/REPO. Daí, em seu repositório, vá para More options > Setting e navegue até a seção Environment Variables.
Crie uma nova variável de ambiente chamada GH_TOKEN com seu token recém-criado como seu valor. Depois, crie GH_EMAIL (seu endereço de e-mail) e GH_NAME (seu nome de usuário do GitHub).
Crie um .travis.yml na raiz do seu repositório contendo o texto abaixo.

# .travis.yml
language: node_js
node_js:
  - '8'
branches:
  only:
    - master
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
  - cd website && yarn install && GIT_USER="${GH_NAME}" yarn run publish-gh-pages

Agora, sempre que um novo commit pintar na branch master, o Travis CI vai rodar sua bateria de testes e, se tudo passar, seu site será publicado através do script publish-gh-pages.

Hosting on ZEIT Now

With ZEIT Now, you can deploy your site and connect it to GitHub or GitLab to automatically receive a new deployment every time you push a commit.

Hospedando no Netlify

Siga estes passos para configurar seu site Docusaurus no Netlify:

Selecione New site from Git
Conecte ao provedor Git de sua preferência.
Selecione a branch a ser publicada. A padrão é a master
Configure as etapas do processo de build:

Como comando de build, insira: cd website; npm install; npm run build;
Como diretório de publicação: website/build/<nomeDoProjeto> (use o nomeDoProjeto que está lá no seu siteConfig)

Clique em Deploy site

Você também pode configurar o Netlify para repetir esse processo a cada commit no seu repositório, ou apenas para commits na branch master.

Hosting on Render

Render offers free static site hosting with fully managed SSL, custom domains, a global CDN and continuous auto deploys from your Git repo. Deploy your app in just a few minutes by following these steps.

Create a new Web Service on Render, and give Render's GitHub app permission to access your Docusaurus repo.
Selecione a branch a ser publicada. The default is master.
Enter the following values during creation.

Field	Value
Environment	`Static Site`
Build Command	`cd website; yarn install; yarn build`
Publish Directory	`website/build/<projectName>`

`projectName` is the value you defined in your `siteConfig.js`.

const siteConfig = {
  // ...
  projectName: 'your-project-name',
  // ...

That's it! Your app will be live on your Render URL as soon as the build finishes.

Publicando no GitHub Enterprise

Publicar no GitHub Enterprise deve funcionar da mesma maneira que no GitHub.com; você só precisa identificar o host da organização no GitHub Enterprise.

Nome	Descrição
`GITHUB_HOST`	O nome do host para o servidor GitHub Enterprise.

Altere o seu siteConfig.js para adicionar uma propriedade 'githubHost', que representa o nome do host no GitHub Enterprise. Como alternativa, você pode definir uma variável de ambiente GITHUB_HOST ao executar o comando de publicação.