Generowanie mapy przekierowań z Aliasów w Hugo

Hugo posiada możliwość udostępniania stron pod różnymi adresami za pomocą aliasów, które “przekierowują” do głównej treści. Może to być bardzo przydatne przy zmianach adresu danej podstrony. Ja nie korzystam z tego mechanizmu, ale chciałem sprawdzić czy można zmusić Hugo do wygenerowania pliku z mapą przekierowań (redirects.txt), bazując na zdefiniowanych w treści aliasach. To pozwoliłoby przekształcić je w pełnoprawne przekierowania 301.

Aliasy w Hugo

Dokumentacja dotycząca aliasów jest dość krótka i w prosty sposób opisuje działanie tego mechanizmu.

Aliasy definiowane są w meta nagłówku (front matter) danej treści w polu aliases (tablica):

---
title: Strona o mnie
url: /pages/about.html
...
aliases: [ /about.html, o-mnie ]
---

W domyślnej konfiguracji Hugo dla każdego aliasu wygeneruje prosty plik HTML z Meta Refresh, czyli “emulacją” przekierowania za pomocą strony wymuszającej na przeglądarce odświeżenie strony wraz z przejściem do podanej lokalizacji. Wykorzystywana jest dyrektywa http-equiv zawarta w metadanych nagłówka (<head/>) strony:

<meta http-equiv="refresh" content="0; url=http://example.com/pages/about.html"/>

Jest to przekierowanie po stronie przeglądarki/klienta i różni się ono od tego prawdziwego - po stronie serwera - brakiem wysłania poprawnych kodów (301, 302, …) w nagłówku odpowiedzi HTTP.

Nowy format Redirects

Do masowych przekierowań po stronie serwera potrzebna jest “mapa”, którą o dziwo również łatwo daje się wygenerować bezpośrednio w Hugo i do tego wprost ze zdefiniowanych aliasów. Najprostszym sposobem wydaje się wykorzystanie do tego celu nowego dedykowanego formatu wyjściowego.

W pliku konfiguracyjnym dodałem minimalne definicje nowego formatu i włączyłem go dla strony głównej:

outputs:
  home: [ HTML, ATOM, REDIRECTS ]

outputFormats:
  REDIRECTS:
    name: REDIRECTS
    mediaType: text/plain
    baseName: redirects
    isPlainText: true
    notAlternative: true

Bo w zamierzeniu ma powstać tylko jeden plik redirects.txt z pełną mapą dla całej witryny.

W pliku szablonu layouts/index.redirects.txt znajduje się iteracja po wszystkich aliasach stron:

#
# Auto-generated redirects map file
#

{{ range .Site.Pages -}}
	{{- $to := .RelPermalink -}}
	{{- range $from := .Aliases -}}
		{{- print $from " " $to "\n" -}}
	{{- end -}}
{{- end }}

Teraz przy budowaniu strony przez Hugo utworzony zostanie plik redirects.txt zawierający listę wszystkich przekierowań zdefiniowanych aliasami w treściach strony.

Dla przykładowych aliasów (z początku tego wpisu) treść tego pliku przedstawiałaby się następująco:

#
# Auto-generated redirects map file
#

/about.html /pages/about.html
o-mnie /pages/about.html

Jak widać poprawnie obsłużono tylko aliasy zdefiniowane jako “absolutne”, a w gwoli ścisłości - relatywne względem roota strony (BaseURL). Do obsługi także wpisów relatywnych względem danej strony trzeba rozbudować ten prosty szablon o kod dokonujący dodatkowych przekształceń takich wpisów:

{{- if not (hasPrefix $from "/") -}}
	{{- $base := path.Dir (strings.TrimRight "/" $to) -}}
	{{- $from = relURL (print $base "/" $from) -}}
{{- end -}}

W wyniku czego mapa powinna zawierać już wszystkie poprawne wpisy:

/about.html /pages/about.html
/pages/o-mnie /pages/about.html

Nie testowałem tego kodu zbyt dokładnie, gdyż ogólną praktyką powinno być unikanie aliasów z relatywnymi wpisami. Lepiej zawsze specyfikować pełny adres względem / strony, bo to zapewni zawsze poprawne przekierowania, nawet gdy zmienimy schemat generowania odnośników lub strukturę organizacyjną plików witryny lub kontentu.

Dodatkowo na koniec warto wyłączyć w konfiguracji automatyczne generowanie wbudowanych w Hugo aliasów HTML:

disableAliases: true

One już nie będą potrzebne. Generowany przy budowie strony plik redirects.txt zawiera pełną mapę przekierowań, którą można wykorzystać w konfiguracji web-serwera lub hostingu do przeprowadzania przekierowań HTTP.

Tworzenie plików przez formaty wyjściowe

Wykorzystując dostępną w Hugo funkcjonalność generowania dowolnych formatów wyjściowych można w łatwy sposób generować dowolny inny plik wyjściowy bez potrzeby tworzenia związanego z nim jakiegokolwiek pliku źródłowego (treści). Pozwala to zachować porządek i “czystość” w miejscu przechowywania kontentu strony. Dodatkowo takie pliki nie pojawiają się w innych miejscach wygenerowanej zawartości strony - sitemap, feedy, etc… Co mógłby być problematyczne przy tworzeniu specyficznych plików, jak ten opisany w dzisiejszym poście.

Oczywiście nie jest to jedyna możliwa metoda na generowanie specyficznych plików przy budowaniu strony w Hugo. Inny sposób pewnie przedstawię w następnym wpisie, gdzie będę chciał utworzyć również plik redirects.txt, ale z danych zawartych w mojej specyficznej strukturze przechowującej treści dla tej strony.

Wygląda na to, że nie tylko ja wpadłem na tworzenie plików przez dedykowane formaty wyjściowe. Temat ten był już poruszany w sieci, a nawet na blogu Hugo, gdzie wykorzystano go do stworzenia pliku _redirects z podobna mapą przekierowań dla usługi Netlify.