Weiterleitungen

Weiterleitungen

Halte eine alte URL funktionsfähig, nachdem du eine Seite verschiebst, umbenennst oder umstrukturierst - an der alten URL wird ein statischer HTML-Stub geschrieben, sodass ein veralteter Index-Eintrag einer Suchmaschine oder jemandes altes Lesezeichen weiterhin auf der richtigen Seite landet, statt einen 404 zu liefern. Es ist keine serverseitige Rewrite-Regel beteiligt (ein statischer Host hat nirgendwo, um eine auszuführen) - der Stub ist gerade genug HTML, damit ein Browser sich selbst weiterleitet und ein Crawler die echte kanonische URL erfährt.

Pro Seite: Frontmatter redirect_from

Füge einen oder mehrere alte Pfade zur eigenen Frontmatter einer Seite hinzu:

---
title: New Setup
redirect_from:
  - guides/old-setup
  - setup
---

Jeder Eintrag ist ein hübsches URL-Segment - kein führender/abschließender Schrägstrich, keine .md/.html-Dateiendung - dieselbe Form, die die eigene URL der Seite annimmt. Ein Build schreibt dann für jeden einen Stub (site/guides/old-setup/index.html, site/setup/index.html für das obige Beispiel), die beide zur echten eigenen URL dieser Seite weiterleiten.

redirect_from ist auf den jeweiligen Baum beschränkt, zu dem die Seite selbst gehört - die eigene Seite einer Version leitet innerhalb dieser Version weiter (site/versions/2.0/old-path/), die eigene übersetzte Seite einer Locale leitet innerhalb dieser Locale weiter (site/es/old-path/), genau so, wie es die eigene echte URL der Seite bereits tut. Es gibt nichts Zusätzliches pro Baum zu konfigurieren.

Websiteweit: bxsites.yaml redirects

Für eine alte URL, die nie zu einer bestimmten Seite gehörte - ein umstrukturierter Abschnitt, der Pfad einer alten Domain, alles, was nicht natürlich der eigene "alte Name" einer einzelnen Seite ist - liste stattdessen ein explizites from/to-Paar auf:

redirects:
  - from: old-guide
    to: guides/new-guide/
  - from: moved-to-another-site
    to: https://example.com/docs

{
	"redirects": [
		{ "from": "old-guide", "to": "guides/new-guide/" },
		{ "from": "moved-to-another-site", "to": "https://example.com/docs" }
	]
}

• from - das alte hübsche URL-Segment, dieselbe Form wie redirect_from oben
• to - entweder ein root-relativer Pfad (aufgelöst gegen die eigene baseURL der Site, dieselbe Konvention, die theme.logo/ogImage bereits verwenden) oder eine vollständige https://-URL, um komplett auf eine andere Site weiterzuleiten

redirects gilt immer nur für den Hauptbaum der Site - ein bloßes to ist ein root-relativer Pfad, der nur an der Site-Wurzel eindeutig ist. Ein Versions-/Locale-Baum, der dieselbe alte URL-Zuordnung möchte, braucht stattdessen sein eigenes seitenbezogenes redirect_from.

page:rename setzt das für dich

Das Umbenennen/Verschieben einer Seite mit page:rename fügt ihren alten Pfad automatisch dem eigenen redirect_from der verschobenen Seite hinzu - zusätzlich zum Umschreiben jedes relativen Markdown-Links, der darauf zeigte, funktioniert auch die alte URL selbst weiter:

bxSites page:rename --from=guides/old-setup.md --to=guides/new-setup.md

Eine Seite mehr als einmal umzubenennen, fügt einfach weiter hinzu - die redirect_from-Liste einer Seite kann so viele alte Pfade tragen, wie sie im Laufe der Zeit hatte.

Konflikte

Ein Build schlägt komplett fehl, statt echten Inhalt stillschweigend zu überschreiben, wenn:

• Der eigene from-Pfad einer Weiterleitung mit einer echten Seite kollidiert, die bereits an diesem Pfad gebaut wurde (BxSites.RedirectConflict)
• Zwei Weiterleitungen (redirect_from-Einträge, redirects-Konfigurationseinträge, oder einer von jedem) beide denselben from-Pfad anvisieren

Was (vorerst) außen vor bleibt

• Blogbeiträge erhalten kein redirect_from. Der Frontmatter-Schlüssel wird nur für reguläre docs/-Seiten gelesen, nicht für docs/blog/posts/** - ein verschobener Blogbeitrag braucht stattdessen seinen eigenen redirects-Konfigurationseintrag.
• Keine Wildcard-/Muster-Weiterleitungen. Jedes from ist ein exakter alter Pfad - es gibt kein guides/old/*-Catch-all.