Translate

Publishing your site

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.

Por exemplo, tanto o Apache quanto o nginx servem conteúdo a partir do diretório /var/www/html por padrão. 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. No caso do nginx, isso significaria definir include /etc/nginx/mime.types; no seu arquivo nginx.conf. See this issue for more info.

Hospedando em um serviço:

• ZEIT Now
• GitHub Pages
• Netlify

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:

1. First, install their command-line interface:

npm i -g now

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

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

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

3. 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:

1. 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.
2. Faça login no GitHub como o GIT_USER.
3. 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.
4. 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.
5. Crie uma nova variável de ambiente chamada GITHUB_TOKEN, usando seu token de acesso recém-criado como o valor dela.
6. Crie um diretório .circleci e crie um arquivo config.yml dentro dele.
7. 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. Nós já configuramos esse token como uma variável lá no passo 3.

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.

Diferentemente de quando você roda o script publish-gh-pages manualmente, quando você roda ele dentro do ambiente do CircleCI, o valor de CURRENT_BRANCH já está definido como uma variável de ambiente dentro do CircleCI e será usado pelo script automaticamente.

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

1. Vá para https://github.com/settings/tokens e gere um novo token de acesso pessoal
2. Usando sua conta do GitHub, adicione o app Travis CI ao repositório que você deseja ativar.
3. 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.
4. 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).
5. 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:

1. Selecione New site from Git
2. Conecte ao provedor Git de sua preferência.
3. Selecione a branch a ser publicada. A padrão é a master
4. 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)

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

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.