Antes de montar EmDash en una subruta: hicimos clic en cada dirección bajo /field-notes

Después de definir base en Astro, qué direcciones se mueven con él y cuáles no, y algunos lugares que conviene revisar a mano antes de publicar.

Poner un sitio bajo example.com/field-notes/ en lugar de darle un dominio entero es un requisito frecuente: el sitio principal es otro sistema y el blog es solo una sección colgada debajo.

El ajuste correspondiente en Astro es una sola línea, base. Por eso pensamos que esta guía sería corta.

Luego creamos un sitio nuevo con la plantilla de blog, definimos base: "/field-notes", compilamos, arrancamos y llamamos a cada dirección con curl. Había más cosas que esa sola línea. Esto es lo que vimos realmente.

Entorno de prueba: EmDash 1.4.0, adaptador Node, SQLite, la plantilla de blog oficial, con los 8 artículos de ejemplo de la plantilla cargados mediante emdash seed.

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

¿Qué direcciones se movieron con base?

Primero la buena noticia. Las páginas en sí funcionan:

DirecciónResultado
/field-notes/200
/field-notes/posts200
/field-notes/rss.xml200
/field-notes/robots.txt200

¿Qué direcciones se quedaron donde estaban?

La administración y la API se quedan en su sitio:

DirecciónResultado
/_emdash/api/health200
/_emdash/admin302, redirige a /_emdash/admin/setup

Es decir, todo lo que empieza por /_emdash no se mueve a /field-notes. La regla de enrutamiento que tengas delante debe enviar a esta aplicación tanto /field-notes/* como /_emdash/*. Si envías solo la primera, la administración no se abrirá.

Otras dos direcciones con las que nos topamos merecen mención: /field-notes/_emdash/api/health y /field-notes/sitemap.xml devuelven ambas 500. No son direcciones que nadie deba visitar, pero si tu script de comprobación funciona con el principio «añade el prefijo y reintenta», te darán un susto.

Algo más nos sorprendió: la ruta raíz / y /posts también devuelven 200. Es decir, el mismo contenido tiene dos entradas. Si no quieres que los buscadores vean dos copias, haz que tu enrutamiento delantero deje pasar solo /field-notes/* y /_emdash/* y rechace todo lo demás.

Ni un solo enlace de las páginas lleva el prefijo

Este es el punto que menos esperábamos. Abre la página de inicio en /field-notes/ y mira el código fuente. Los enlaces son así:

  • 7 artículos: cosas como /posts/a-weekend-with-a-side-project
  • 4 etiquetas: cosas como /tag/opinion
  • la barra de navegación: /, /pages/about, /posts
  • además de /rss.xml y /search

Ninguno lleva /field-notes. Al hacer clic sales de tu subruta y caes bajo la ruta raíz.

Los enlaces vienen de dos sitios, y se corrigen en lugares distintos:

  1. Escritos a mano en el código de la plantilla. Por ejemplo href={`/tag/${t.slug}`} en src/pages/posts/[slug].astro, y el href="/posts" que aparece en varias páginas. Hay que reescribirlos para que empiecen por import.meta.env.BASE_URL.
  2. Guardados en la base de datos. Los tres elementos de navegación no están escritos en la plantilla. Son datos de menú, almacenados en la tabla _emdash_menu_items, y sus direcciones son /, /pages/about y /posts. Si solo cambias la plantilla, la barra de navegación no se mueve en absoluto. Tienes que cambiar las direcciones de los propios elementos del menú, o cambiar el archivo de seed y volver a cargarlo.

La forma en que se escriben estos enlaces en esta plantilla es una decisión de la propia plantilla. No es un problema causado por el ajuste base. Tampoco reescribimos toda la plantilla para luego verificarla, así que aquí solo podemos decirte dónde buscar. No podemos prometer que todo quede correcto una vez cambiados.

Las direcciones que leen las máquinas tampoco llevan prefijo

Además de los enlaces que ven las personas, hay tres cosas que leen las máquinas, y también las revisamos:

  • Las direcciones listadas en /sitemap.xml son del estilo .../sitemap-posts.xml, y las de los artículos dentro, del estilo .../posts/the-case-for-static. Ninguna lleva /field-notes.
  • El <link> de cada elemento del RSS es igualmente .../posts/....
  • El /robots.txt de la raíz contiene Disallow: /_emdash/ y apunta al mapa del sitio, mientras que /field-notes/robots.txt solo contiene User-agent: * y Allow: /, sin el bloqueo de /_emdash/ y sin el mapa del sitio.

El último punto merece reflexión: los buscadores solo leen robots.txt en la raíz del dominio. El que está bajo la subruta, en la práctica, no lo lee nadie. Si tu sitio principal no es EmDash, tienes que bloquear tú mismo /_emdash/ en el robots.txt del sitio principal.

Que el mapa del sitio y el RSS no tengan prefijo significa que las direcciones que envíes a los buscadores serán direcciones fuera de la subruta. Solo observamos el comportamiento. No rastreamos qué línea de código lo decide.

El modo de desarrollo te engaña

Empezamos probando con astro dev, y esto fue lo que salió:

  • /_emdash/api/health devolvió 500, con Cannot read properties of undefined (reading 'registry') en el registro.
  • /sitemap.xml devolvió 500, con el contenido EmDash not configured.

Pensamos que base había roto el entorno de ejecución. Al quitar base, las dos direcciones volvieron a 200, lo que nos convenció aún más.

Hasta que cambiamos a ejecutar primero astro build y luego arrancar con node ./dist/server/entry.mjs. Con base definido, las dos direcciones anteriores devuelven 200.

Así que no uses el modo de desarrollo para juzgar si una subruta está bien configurada. No averiguamos por qué difieren los dos modos.

Lo que haríamos a mano antes de publicar

  1. Compilar, arrancar y mirar con curl el código fuente de la página de inicio de /field-notes/. Buscar enlaces que empiecen por href="/ pero no contengan /field-notes.
  2. Abrir /_emdash/admin y confirmar que tu regla de enrutamiento delantera lo envía a la aplicación.
  3. Echar un vistazo a las direcciones de sitemap.xml y rss.xml.
  4. Confirmar en el robots.txt del sitio principal que /_emdash/ está bloqueado.
  5. Visitar / y /posts y decidir si quieres que existan.

Lo que no probamos

  • No pusimos la regla de enrutamiento en un Cloudflare Worker o nginx reales. Lo que decimos arriba sobre enviar tanto /field-notes/* como /_emdash/* se deduce del comportamiento observado.
  • No probamos el adaptador de Cloudflare, solo Node.
  • No reescribimos los enlaces de toda la plantilla.

Si puedes evitar una subruta y usar un subdominio aparte, te ahorras la mayor parte de lo que trata este artículo.