Antes de montar o EmDash em um subcaminho: clicamos em cada endereço sob /field-notes

Depois de definir base no Astro, quais endereços se movem junto e quais não, e alguns lugares que vale a pena conferir à mão antes de publicar.

Colocar um site em example.com/field-notes/ em vez de lhe dar um domínio inteiro é uma necessidade comum: o site principal é outro sistema, e o blog é apenas uma seção pendurada embaixo.

A configuração correspondente no Astro é uma única linha, base. Por isso achamos que este guia seria curto.

Depois criamos um site novo com o modelo de blog, definimos base: "/field-notes", fizemos o build, iniciamos e chamamos cada endereço com curl. Havia mais coisa do que essa linha. Eis o que vimos de fato.

Ambiente de teste: EmDash 1.4.0, adaptador Node, SQLite, o modelo de blog oficial, com os 8 artigos de exemplo do modelo carregados por emdash seed.

export default defineConfig({
  output: "server",
  base: "/field-notes",
  // ...
});

Quais endereços se moveram com o base?

Primeiro a boa notícia. As páginas em si estão bem:

EndereçoResultado
/field-notes/200
/field-notes/posts200
/field-notes/rss.xml200
/field-notes/robots.txt200

Quais endereços ficaram onde estavam?

A administração e a API ficam no lugar:

EndereçoResultado
/_emdash/api/health200
/_emdash/admin302, redireciona para /_emdash/admin/setup

Ou seja, tudo o que começa com /_emdash não se muda para /field-notes. A regra de roteamento que você tem na frente precisa enviar a esta aplicação tanto /field-notes/* quanto /_emdash/*. Se enviar só a primeira, a administração não abre.

Outros dois endereços em que esbarramos merecem menção: /field-notes/_emdash/api/health e /field-notes/sitemap.xml retornam ambos 500. Não são endereços que alguém deva visitar, mas se o seu script de verificação funciona pelo princípio «coloque o prefixo e tente de novo», eles vão assustar você.

Outra coisa nos surpreendeu: o caminho raiz / e /posts também retornam 200. Ou seja, o mesmo conteúdo tem duas entradas. Se você não quer que os mecanismos de busca vejam duas cópias, faça o seu roteamento da frente deixar passar apenas /field-notes/* e /_emdash/* e rejeitar todo o resto.

Este é o ponto que menos esperávamos. Abra a página inicial em /field-notes/ e veja o código-fonte. Os links são assim:

  • 7 artigos: coisas como /posts/a-weekend-with-a-side-project
  • 4 tags: coisas como /tag/opinion
  • a barra de navegação: /, /pages/about, /posts
  • além de /rss.xml e /search

Nenhum leva /field-notes. Ao clicar, você sai do seu subcaminho e cai sob o caminho raiz.

Os links vêm de dois lugares, e se corrigem em lugares diferentes:

  1. Escritos diretamente no código do modelo. Por exemplo href={`/tag/${t.slug}`} em src/pages/posts/[slug].astro, e o href="/posts" que aparece em várias páginas. Precisam ser reescritos para começar com import.meta.env.BASE_URL.
  2. Guardados no banco de dados. Os três itens da navegação não estão escritos no modelo. São dados de menu, armazenados na tabela _emdash_menu_items, e seus endereços são /, /pages/about e /posts. Se você mudar só o modelo, a barra de navegação não se mexe. É preciso mudar os endereços dos próprios itens do menu, ou mudar o arquivo de seed e carregá-lo de novo.

O modo como esses links estão escritos neste modelo é uma escolha do próprio modelo. Não é um problema causado pela configuração base. Também não reescrevemos o modelo inteiro para depois verificar, então aqui só podemos dizer onde procurar. Não podemos prometer que tudo fique certo depois de mudá-los.

Os endereços lidos por máquinas também não têm prefixo

Além dos links que as pessoas veem, há três coisas lidas por máquinas, e olhamos para elas também:

  • Os endereços listados em /sitemap.xml têm a forma .../sitemap-posts.xml, e os endereços dos artigos dentro dele têm a forma .../posts/the-case-for-static. Nenhum contém /field-notes.
  • O <link> de cada item do RSS é igualmente .../posts/....
  • O /robots.txt da raiz contém Disallow: /_emdash/ e aponta para o mapa do site, enquanto /field-notes/robots.txt contém apenas User-agent: * e Allow: /, sem o bloqueio de /_emdash/ e sem o mapa do site.

O último ponto merece reflexão: os mecanismos de busca só leem o robots.txt na raiz do domínio. O que está sob o subcaminho, na prática, ninguém lê. Se o seu site principal não é EmDash, você precisa bloquear /_emdash/ por conta própria no robots.txt do site principal.

O fato de o mapa do site e o RSS não terem prefixo significa que os endereços que você envia aos mecanismos de busca serão endereços fora do subcaminho. Apenas observamos o comportamento. Não rastreamos qual linha de código o determina.

O modo de desenvolvimento engana

Começamos testando com astro dev, e foi isto que saiu:

  • /_emdash/api/health retornou 500, com Cannot read properties of undefined (reading 'registry') no registro.
  • /sitemap.xml retornou 500, com o conteúdo EmDash not configured.

Achamos que o base tinha quebrado o ambiente de execução. Ao remover o base, os dois endereços voltaram a 200, o que nos convenceu ainda mais.

Até que mudamos para rodar primeiro astro build e depois iniciar com node ./dist/server/entry.mjs. Com o base definido, os dois endereços acima retornam 200.

Portanto, não use o modo de desenvolvimento para julgar se um subcaminho está configurado corretamente. Não descobrimos por que os dois modos diferem.

O que conferiríamos à mão antes de publicar

  1. Fazer o build, iniciar e olhar com curl o código-fonte da página inicial de /field-notes/. Procurar links que comecem com href="/ mas não contenham /field-notes.
  2. Abrir /_emdash/admin e confirmar que a sua regra de roteamento da frente o envia à aplicação.
  3. Dar uma olhada nos endereços de sitemap.xml e rss.xml.
  4. Confirmar no robots.txt do site principal que /_emdash/ está bloqueado.
  5. Visitar / e /posts e decidir se você quer que existam.

O que não testamos

  • Não colocamos a regra de roteamento em um Cloudflare Worker ou nginx reais. O que dizemos acima sobre enviar tanto /field-notes/* quanto /_emdash/* é deduzido do comportamento observado.
  • Não testamos o adaptador do Cloudflare, só o Node.
  • Não reescrevemos os links do modelo inteiro.

Se você puder dispensar um subcaminho e usar um subdomínio separado, evita a maior parte do que este artigo trata.