Pri budovaní statickej stránky so Zolou je jedným z bežných problémov objavenie nefunkčných interných odkazov až po nasadení. Externé odkazy smerujúce na váš vlastný obsah (napríklad [príspevok](/blog/moj-prispevok/)) sú Zolou považované za externé, čím sa prichádza o cennú príležitosť na validáciu. Tu je postup, ako som skonvertoval všetky externé sebareferencujúce odkazy na správne interné a aké výhody to prinieslo.

Externé odkazy tváriacé sa ako interné #

Spočiatku moje blogové príspevky obsahovali takéto odkazy:

[dôležitý príspevok](/blog/insights-google-search-console/#trailing-slash-inconsistency)
[súvisiaci článok](/blog/using-uuid-in-atom-feed/#url-vs-urn-which-one-to-choose)

Hoci pre čitateľov fungujú dobre, Zola ich považuje za externé, pretože začínajú na /. To znamená:

  • Žiadna validácia odkazov počas buildovania
  • Žiadna kontrola kotiev
  • Potenciál pre nefunkčné odkazy, ktoré prejdú nepovšimnuté

Nie som si istý, ako mi to uniklo až teraz. Ale hej, každý deň sa niečo naučíme!

Nezrovnalosť pri kontrole odkazov #

Tento problém som skutočne objavil pri spustení zola check:

Checking site...
Checking all internal links with anchors.
> Successfully checked 1 internal link(s) with anchors.

Rovnaký výstup sa objavuje aj pri zola build alebo zola serve, ale kto to číta, keď nie sú žiadne červené chyby, však? Keď som však hľadal všetky interné odkazy s kotvami:

rg '\[([^\]]+)\]\((/blog/[^)]+)\)' | rg '#'

Našiel som 6 rôznych odkazov, nie jeden! Nezrovnalosť odhalila, že len jeden odkaz bol považovaný za skutočne interný — sebareferencujúci kotevný odkaz:

[Databáza Postgres](#postgres-database)

Jasne mi niečo unikalo.

Konverzia na Zolinu interného odkazu syntaxu #

Zola poskytuje špeciálnu syntax pre interné odkazy pomocou @/, ktorá umožňuje správnu validáciu. Potreboval som konvertovať odkazy z:

[text](/blog/nazov-prispevku/#kotva)

Na:

[text](/blog/nazov-prispevku/#kotva)

Takto je to trochu ťažšie, pretože musíte odkazovať na skutočný fyzický súbor, nie len na URL, ktorá mu bude priradená. Má to však zmysel, keďže URL môže byť konfigurovaná a menená podľa vôle.

Krok 1: Folderizácia príspevkov #

Keďže niektoré moje príspevky boli už v priečinkoch (kvôli obrázkom) a iné nie, najprv som zjednotil štruktúru “folderizáciou” všetkých príspevkov pomocou skriptu, ktorý používam:

#!/bin/bash

for file in content/blog/*.md
    if test -f "$file" && not string match -q "*/index.md" "$file"
        filename=$(basename "$file" .md)
        mkdir "content/blog/$filename"
        mv "$file" "content/blog/$filename/index.md"
    end
end

Predtým štruktúra priečinkov vyzerala takto:

content/blog/
├── setting-url-prefix-in-zola.md
├── using-electronic-id-on-arch.md
├── optimize-many-pdfs-at-once.md
├── high-cpu-usage-with-pcscid.md
├── install-php7-with-composer.md
└── running-mastodon-with-docker/     # už folderizovaný
    └── index.md
    └── docker.png

Po zjednotení bola konzistentná:

content/blog/
├── setting-url-prefix-in-zola/
│   └── index.md
├── using-electronic-id-on-arch/
│   └── index.md
├── optimize-many-pdfs-at-once/
│   └── index.md
├── high-cpu-usage-with-pcscid/
│   └── index.md
├── install-php7-with-composer/
│   └── index.md
└── running-mastodon-with-docker/     # nezmenený
    └── index.md
    └── docker.png

Je to dôležité aj preto, lebo pri písaní interného odkazu si pravdepodobne nepamätáte, či je príspevok “folderizovaný” alebo nie. Konzistentnosť odstraňuje potenciálne problémy a znižuje mentálnu záťaž. Zároveň zjednodušuje ďalší krok a zabraňuje regulárno-výrazovému peklu.

Krok 2: Konverzia odkazov #

Po niekoľkých iteráciách bol finálny funkčný príkaz pre fish shell:

sd '\[([^\]]+)\]\(/blog/([^/)]+)/?(\)|#[^)]*\))' '[$1](@/blog/$2/index.md$3' content/blog/**/*.md

Čo robí:

  • \[([^\]]+)\] — zachytáva text odkazu
  • \(/blog/([^/)]+)/? — zodpovedá /blog/nazov-prispevku s voliteľným lomítkom na konci
  • (\)|#[^)]*\)) — zachytáva buď ) alebo #kotva)
  • Nahrádza správnou Zolinou syntaxou interného odkazu

Čomu zabraňuje:

  • Odstraňovaniu koncovej interpunkcie: Príliš jednoduché regulárne výrazy zachytávali čiarky a inú interpunkciu

    -[nemohol som písať z telefónu](/blog/prispevok/),
+[nemohol som písať z telefónu](@/blog/prispevok.md)

  • Zodpovedaniu externých URL: Príliš všeobecné regulárne výrazy zodpovedali /blog/ v externých URL ako https://docker.com/blog/prispevok, čím vznikali deformované odkazy:

    could not parse domain `https://www.docker.com@/blog/post/index.md` from link: `empty host`

Spustenie zola check bolo úspešné, git diff vyzeralo dobre, takže to pre môj prípad použitia vyzerá správne.

Robustná validácia odkazov #

Po konverzii zola check --skip-external-links teraz správne validuje všetky interné odkazy:

Checking all internal links with anchors.
> Successfully checked 7 internal link(s) with anchors.
-> Site content: 236 pages (0 orphan), 3 sections
Done in 74ms.

Výstup je trochu zavádzajúci. Uvádza, že kontroluje 7 interných odkazov, ale v skutočnosti kontroluje všetky interné odkazy! Len uvádza, že zo všetkých interných odkazov 7 z nich má aj kotvu, ktorá sa ďalej kontroluje — čiže nie len to, že odkazovaná stránka existuje, ale aj to, že nadpis je dostupný cez svoju kotvu. Skúste vložiť preklep do interného odkazu bez kotvy a spustite zola build:

Building site...
Error: Failed to build the site
Error: Failed to render content of ~/my-blog/content/blog/moj-prispevok/index.md
Error: Reason: Broken relative link `@/blog/iny-prispevok/CHYBA-index.md` in blog/moj-prispevok/index.md

Vidíte? Veľmi dobré na včasné odhalenie chýb.

Kľúčové výhody #

  1. Validácia odkazov počas buildu — Zola teraz zachytáva nefunkčné interné odkazy počas buildu, čím zabraňuje nasadeniu nefunkčných stránok.
  2. Overenie kotiev — Systém validuje, že odkazované kotvy skutočne existujú v cieľových príspevkoch.
  3. Bezpečnosť pri refaktorovaní — Pri premenovaní príspevkov alebo reštrukturalizácii obsahu Zola zachytí nefunkčné interné referencie.
  4. Konzistentná štruktúra — Všetky interné odkazy teraz sledujú rovnaký vzor @/blog/prispevok/index.md bez ohľadu na pôvodnú štruktúru súborov.
  5. Dôvera pri vývoji — Žiadne hádanie, či interné odkazy fungujú — proces buildu to garantuje.

Záver #

Konverzia externých sebareferencujúcich odkazov na Zolinu syntax interných odkazov mení správu odkazov z manuálneho, chybového procesu na automatizovaný, validovaný systém. Počiatočné nastavenie vyžaduje trochu práce s regulárnymi výrazmi, ale dlhodobé výhody zachytávania nefunkčných odkazov počas buildu ďaleko prevyšujú vynaložené úsilie.

Ak prevádzkujete stránku na Zole s internými odkazmi, dôrazne odporúčam vykonať túto konverziu. Vaše budúce ja vám poďakuje pri refaktorovaní obsahu alebo reštrukturalizácii stránky. Vychutnajte si!

Odkazy #