Generowanie mapy przekierowań z Aliasów w Hugo

tech • 600 słów • 3 minuty czytania

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.

Komentarze (0)

Dodaj komentarz

/dozwolony markdown/

/nie zostanie opublikowany/