Olá! 👋 Você, provavelmente, está aqui porque quer hospedar dois sites/repositórios em um site usando o Netlify ou já está lidando com isso.

Talvez você já tenha verificado as respostas na página da comunidade do Netlify e ainda continue confuso.

Saiba que a mesma confusão e dor de cabeça me levaram a escrever este tutorial para você não precisar se esforçar tanto quanto eu precisei. :)

Adianto apenas que é um pouco complicado, mas funciona: a solução para esse problema é o arquivo netlify.toml ou o _redirects.

Vamos começar!

Estou trabalhando em um projeto com alguns colegas e resolvemos dividir as tarefas. Eu fiquei com a documentação.

Tecnologias que usaremos

• O Docusaurus para fazer sites bonitos de documentação em pouco tempo.
• O Next.js/React.js para o nosso site principal.

Podemos hospedar a documentação de duas formas:

1. Usando um subdomínio: docs.siteprincipal.dev
2. Hospedando como um subdiretório: siteprincipal.dev/docs.

Baseado em outros projetos de documentação que vi sendo implementados, também resolvi hospedá-lo no Netlify como um subdiretório.

Acho que isso dá um aspecto mais profissional à documentação.

Se você também quiser hospedar o Docusaurus como subdiretório, precisará fazer algumas configurações.

Etapa 1 – Atualizar o URL base

Alteraremos o URL base no arquivo docusaurus.config.js para "/docs/", desta forma:

  title: 'Seu Título de Documentação',
  tagline: 'Seu slogan de documentação',
  url: 'meu-site-de-documentacao.netlify.app',
  baseUrl: "/docs/",
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: '/favicon.ico',

Quando alteramos o URL base para /docs/, estamos fazendo com que nosso site de documentação seja renderizado exatamente no endereço https://siteprincipal.dev/docs/.

Se tivéssemos definido o URL base como "/", ocorreria um erro, pois entraria em conflito com o URL do site principal. Fazendo a alteração, também não teremos o trabalho de lidar com o proxy no site da documentação.

Etapa 2 – Atualizar o routeBasePath

Precisamos, além disso, nos certificar de que o conteúdo da documentação seja veiculado a partir do domínio principal, alterando o routeBasePath para "/".

Desse modo, temos:

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          routeBasePath: '/',
        },
      }),
    ],
  ],

Isso ativa no docusaurus o modo "somente documentação", que faz com que toda a documentação seja enviada a partir do domínio principal, mas com o caminho '/docs/' como caminho de base.

Depois dessas configurações, já conseguimos executar o comando npx docusaurus start no localhost para ver se o site da documentação é compilado e renderizado sem problemas.

Se não tiver problemas, você deve ver algo assim:

Para ler mais sobre as configurações do modo "somente documentação" no docusaurus, a documentação dele está aqui (em inglês).

Etapa 3 – Fazer a implantação (deploy) no Netlify

Agora, é hora de implantarmos o site da documentação no Netlify, que é quando o colocamos no ar. Se você ainda não sabe como fazer isso, confira aqui (texto em inglês).

Quando finalizarmos a implantação, o URL do site no Netlify ficará assim: meu-site-de-documentacao.netlify.app.

Etapa 4 - Fazer o redirecionamento por Proxy

Aqui é a parte em que se faz o redirecionamento da página (ou proxying).

Já hospedamos tanto o site principal quanto o site da documentação no Netlify.

Agora, precisamos criar um arquivo netlify.toml na pasta raiz do projeto/repositório do site principal e adicionar nele as seguintes linhas:

[[redirects]]
from = "/docs/*"
to = "https://meu-site-de-documentacao.netlify.app/:splat"
status = 200
force = false

A regra acima garante que, sempre que o caminho /docs/ for consultado no site principal, o site da documentação carregue normalmente no caminho siteprincipal.netlify.app/docs/.

Outra forma de fazer esse proxy é através de site/repositório da documentação. Basta criar um arquivo netlify.toml na raiz do seu site/repositório de documentação e adicionar nele as seguintes linhas:

[[redirects]]
from = "/*"
to = "https://siteprincipal.netlify.app/docs/:splat"
status = 301
force = true

A regra acima garante que, sempre que o caminho "/*" for consultado no site da documentação, ele será carregado normalmente no caminho siteprincipal.netlify.app/docs/.

Observe que o caminho d0 site da documentação no Netlify agora estará quebrado, mas funcionará perfeitamente no subdiretório do site principal.

Já que agora está tudo funcionando e alcançamos nossos objetivos, que assim seja 😁.

OBSERVAÇÃO: nunca adicione as regras ao site da documentação e ao site principal ao mesmo tempo, pois isso causará um conflito de erros "TOO MANY REDIRECTS" (Muitos redirecionamentos).

Então, adicione as regras no site da documentação ou no site principal, mas nunca em ambos.

Vamos responder algumas perguntas

P: Por que é preferível usar o arquivo netlify.toml e não o arquivo _redirects?

Antes dessa alternativa, eu já tinha tentado a forma "fácil", que é o arquivo _redirects. Saiba, porém, que "não é tão fácil assim", porque você terá sempre que copiar o arquivo _redirects para sua pasta build/ ou public/ ao construir seu site no Netlify.

Isso requer que você edite suas configurações de compilação do Netlify assim:

npm run build && cp _redirects public/

Você também pode conseguir o proxy usando o arquivo _redirects. As regras precisam estar neste formato no site principal:

/docs/* https://meu-site-de-documentacao.netlify.app/:splat 200

e neste formato no site da documentação:

/* https://siteprincipal.netlify.app/docs/:splat 301!

P: Por que é preferível usar URLs do Netlify em todas as regras de proxy ao invés de usar um URL de domínio personalizado?

Bem, a comunidade do Netlify aconselha sempre usar URLs do Netlify, pois é uma forma mais confiável de fazer esse redirecionamento.

Conclusão

Parabéns 🎉! Que bom que você chegou ao final desse artigo.

Espero que você tenha aprendido algo novo hoje.

Agora é hora de fazer a implementação e de tornar a documentação do seu projeto mais profissional também, hospedando-a no subdiretório do seu site principal 👏.

Compartilhe este artigo para que outras pessoas possam vê-lo.

Recursos:

• Playground de redirects da Netlify (instruções em inglês)
• [Tutorial de Suporte] Posso implantar vários repositórios em um único site? (em inglês)