Bevor du EmDash unter einem Unterpfad einhängst: Wir haben jede Adresse unter /field-notes durchgeklickt

Welche Adressen mitwandern, nachdem du in Astro base gesetzt hast, welche nicht, und ein paar Stellen, die du vor dem Livegang von Hand prüfen solltest.

Eine Website unter example.com/field-notes/ zu betreiben, statt ihr eine ganze Domain zu geben, ist eine häufige Anforderung: Die Hauptseite ist ein anderes System, und das Blog hängt nur als ein Bereich darunter.

Die passende Einstellung in Astro ist eine einzige Zeile, base. Wir dachten deshalb, diese Anleitung werde kurz.

Dann haben wir eine neue Website mit dem Blog-Template aufgesetzt, base: "/field-notes" gesetzt, gebaut, gestartet und jede Adresse mit curl aufgerufen. Es steckte mehr dahinter als diese eine Zeile. Im Folgenden steht, was wir tatsächlich gesehen haben.

Testumgebung: EmDash 1.4.0, Node-Adapter, SQLite, das offizielle Blog-Template, mit den 8 Beispielbeiträgen des Templates, die wir über emdash seed geladen haben.

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

Welche Adressen sind mit base mitgewandert?

Zuerst die gute Nachricht. Die Seiten selbst sind in Ordnung:

AdresseErgebnis
/field-notes/200
/field-notes/posts200
/field-notes/rss.xml200
/field-notes/robots.txt200

Welche Adressen sind an ihrem Platz geblieben?

Admin-Bereich und API bleiben, wo sie sind:

AdresseErgebnis
/_emdash/api/health200
/_emdash/admin302, Weiterleitung auf /_emdash/admin/setup

Anders gesagt: Alles, was mit /_emdash beginnt, zieht nicht nach /field-notes um. Deine Routing-Regel davor muss sowohl /field-notes/* als auch /_emdash/* an diese Anwendung weiterreichen. Schickst du nur Ersteres, lässt sich der Admin-Bereich nicht öffnen.

Zwei weitere Adressen, auf die wir gestoßen sind, sind erwähnenswert: /field-notes/_emdash/api/health und /field-notes/sitemap.xml liefern beide 500. Das sind keine Adressen, die jemand aufrufen soll, aber wenn dein Prüfskript nach dem Prinzip „Präfix davorsetzen und nochmal versuchen“ arbeitet, erschrecken sie dich.

Noch etwas hat uns überrascht: Auch der Root-Pfad / und /posts liefern 200. Derselbe Inhalt hat also zwei Eingänge. Wenn Suchmaschinen keine zwei Kopien sehen sollen, lass dein vorgeschaltetes Routing nur /field-notes/* und /_emdash/* durch und weise alles andere ab.

Das war der Punkt, mit dem wir am wenigsten gerechnet hatten. Öffne die Startseite unter /field-notes/ und sieh dir den Quelltext an. Die Links sehen so aus:

  • 7 Beiträge: etwa /posts/a-weekend-with-a-side-project
  • 4 Tags: etwa /tag/opinion
  • die Navigationsleiste: /, /pages/about, /posts
  • dazu /rss.xml und /search

Keiner davon trägt /field-notes. Wer klickt, verlässt deinen Unterpfad und landet unter dem Root-Pfad.

Die Links stammen aus zwei Quellen, und sie werden an unterschiedlichen Stellen korrigiert:

  1. Im Template-Code fest eingetragen. Zum Beispiel href={`/tag/${t.slug}`} in src/pages/posts/[slug].astro und das href="/posts", das auf mehreren Seiten vorkommt. Diese müssen so umgeschrieben werden, dass sie mit import.meta.env.BASE_URL beginnen.
  2. In der Datenbank gespeichert. Die drei Navigationseinträge stehen nicht im Template. Es sind Menüdaten, abgelegt in der Tabelle _emdash_menu_items, und ihre Adressen lauten /, /pages/about und /posts. Änderst du nur das Template, rührt sich die Navigationsleiste nicht. Du musst die Adressen der Menüeinträge selbst ändern oder die Seed-Datei ändern und neu laden.

Wie diese Links in diesem Template geschrieben sind, ist die Entscheidung des Templates. Es ist kein Problem, das die Einstellung base verursacht. Wir haben auch nicht das ganze Template umgeschrieben und anschließend geprüft, also können wir dir hier nur sagen, wo du suchen musst. Wir können nicht versprechen, dass danach alles stimmt.

Adressen, die Maschinen lesen, haben ebenfalls kein Präfix

Neben den Links, die Menschen sehen, gibt es drei Dinge, die von Maschinen gelesen werden. Auch die haben wir uns angesehen:

  • Die in /sitemap.xml aufgeführten Adressen sehen aus wie .../sitemap-posts.xml, und die Beitragsadressen darin wie .../posts/the-case-for-static. Keine davon enthält /field-notes.
  • Der <link> jedes Eintrags im RSS-Feed lautet ebenfalls .../posts/....
  • Die /robots.txt im Root enthält Disallow: /_emdash/ und verweist auf die Sitemap, während /field-notes/robots.txt nur User-agent: * und Allow: / enthält, also weder die Sperre für /_emdash/ noch die Sitemap.

Der letzte Punkt verdient etwas Nachdenken: Suchmaschinen lesen robots.txt nur im Root der Domain. Die Datei unter dem Unterpfad liest in der Praxis niemand. Wenn deine Hauptseite nicht EmDash ist, musst du /_emdash/ selbst in der robots.txt der Hauptseite sperren.

Dass Sitemap und RSS kein Präfix haben, bedeutet, dass die Adressen, die du bei Suchmaschinen einreichst, Adressen außerhalb des Unterpfads sind. Wir haben nur das Verhalten beobachtet. Welche Codezeile das bestimmt, haben wir nicht verfolgt.

Der Entwicklungsmodus führt dich in die Irre

Wir haben zuerst mit astro dev getestet, und das kam heraus:

  • /_emdash/api/health lieferte 500, im Log stand Cannot read properties of undefined (reading 'registry').
  • /sitemap.xml lieferte 500, mit dem Inhalt EmDash not configured.

Wir dachten, base habe die Laufzeit kaputt gemacht. Als wir base entfernten, lieferten beide Adressen wieder 200, was uns noch sicherer machte.

Bis wir umgestellt haben: erst astro build, dann Start mit node ./dist/server/entry.mjs. Mit gesetztem base liefern die beiden Adressen dann 200.

Beurteile also nicht im Entwicklungsmodus, ob ein Unterpfad richtig konfiguriert ist. Warum sich die beiden Modi unterscheiden, haben wir nicht herausgefunden.

Was wir vor dem Livegang von Hand durchklicken würden

  1. Bauen, starten und mit curl den Quelltext der Startseite unter /field-notes/ ansehen. Nach Links suchen, die mit href="/ beginnen, aber kein /field-notes enthalten.
  2. /_emdash/admin öffnen und bestätigen, dass deine vorgeschaltete Routing-Regel es an die Anwendung weiterreicht.
  3. Einen Blick auf die Adressen in sitemap.xml und rss.xml werfen.
  4. In der robots.txt der Hauptseite bestätigen, dass /_emdash/ gesperrt ist.
  5. / und /posts aufrufen und entscheiden, ob sie existieren sollen.

Was wir nicht getestet haben

  • Wir haben die vorgeschaltete Routing-Regel nicht auf einem echten Cloudflare Worker oder nginx eingesetzt. Die Aussage oben, es müssten sowohl /field-notes/* als auch /_emdash/* weitergereicht werden, leiten wir aus dem beobachteten Verhalten ab.
  • Wir haben den Cloudflare-Adapter nicht ausprobiert, nur Node.
  • Wir haben die Links im ganzen Template nicht umgeschrieben.

Wenn du ohne Unterpfad auskommst und stattdessen eine eigene Subdomain verwenden kannst, entfällt der größte Teil dessen, worum es in diesem Artikel geht.