V mojom predchádzajúcom príspevku som sa venoval tomu, ako Zola overuje interné odkazy a kotvy pri buildovaní. Keďže uvažujem o migrácii blogu na Astro, potreboval som vyriešiť ten istý problém: ako zabezpečiť, aby fragment odkazy (kotvy) skutočne smerovali na existujúce nadpisy? Tu je opísané, ako som nastavil kontrolu fragment odkazov v Astro pomocou lychee a rehype-slug.

Problém s fragmentmi #

Na rozdiel od Zola, Astro nemá vstavanú validáciu interných odkazov. Čo je ešte problematickejšie, predvolené spracovanie markdownu v Astro vôbec nepridáva atribúty id k nadpisom. To znamená:

  • Fragment odkazy ako #my-heading nebudú fungovať hneď po inštalácii
  • Neexistuje validácia pri buildovaní, že kotvy existujú
  • Nefunkčné fragment odkazy ticho zlyhávajú pre čitateľov

Keďže vytváranie slugov pre nadpisy sa robí v kóde, oproti Zola nastali nejaké zmeny a chcel som ich zachytiť a opraviť.

Krok 1: Pridanie ID k nadpisom #

Prvým krokom je zabezpečenie, aby nadpisy získali atribúty id. Astro používa remark a rehype na spracovanie markdownu, takže som nainštaloval rehype-slug:

npm install rehype-slug

Potom som ho nakonfiguroval v astro.config.mjs:

import rehypeSlug from "rehype-slug"

export default defineConfig({
  markdown: {
    rehypePlugins: [rehypeSlug],
  },
})

Teraz sa nadpis ako:

## My Important Section

Vykreslí ako:

<h2 id="my-important-section">My Important Section</h2>

Krok 2: Vytvorenie odkazovateľných nadpisov #

Hoci to nie je striktne potrebné pre validáciu, je praktické umožniť čitateľom kopírovať odkazy na nadpisy. Pridal som rehype-autolink-headings:

npm install rehype-autolink-headings

A rozšíril konfiguráciu:

import rehypeSlug from "rehype-slug"
import rehypeAutolinkHeadings from "rehype-autolink-headings"

export default defineConfig({
  markdown: {
    rehypePlugins: [
      rehypeSlug,
      [
        rehypeAutolinkHeadings,
        {
          behavior: "append",
          content: {
            type: "text",
            value: " #",
          },
          properties: {
            className: ["astro-anchor"],
          },
        },
      ],
    ],
  },
})

Teraz má každý nadpis pripojený klikateľný odkaz #. Na poradí záleží – rehype-slug musí prísť pred rehype-autolink-headings, pretože tento posledný potrebuje, aby ID už existovali.

Krok 3: Validácia odkazov pomocou Lychee #

Keď teraz nadpisy majú ID, potreboval som spôsob, ako overiť, že všetky fragment odkazy skutočne smerujú na existujúce kotvy. Tu prichádza lychee – rýchly kontrolór odkazov napísaný v Rust.

brew install lychee  # or cargo install lychee

Kľúčový je príznak --include-fragments, ktorý hovorí lychee, aby overil, že ciele kotiev existujú v HTML:

lychee --include-fragments ./dist

Je tu však háčik. Lychee musí skutočne načítať stránky na kontrolu fragmentov, čo znamená, že potrebujeme bežiaci server. Vytvoril som npm skript, ktorý to rieši:

{
  "scripts": {
    "check-links": "astro preview & sleep 2 && lychee --base-url http://localhost:4321 --include 'localhost:4321/blog' --exclude '.*' --include-fragments . ; kill $!"
  }
}

Poďme si rozobrať, čo to robí:

  • astro preview & - spustí preview server na pozadí
  • sleep 2 - počká, kým server bude pripravený
  • lychee --base-url http://localhost:4321 - nastaví základnú URL na kontrolu
  • --include 'localhost:4321/blog' - kontroluje iba stránky blogu
  • --exclude '.*' - vylučuje externé odkazy (zaujímajú nás iba interné)
  • --include-fragments - magický príznak na validáciu kotiev
  • . ; kill $! - skontroluje aktuálny adresár, potom zabije server na pozadí

Porovnanie so Zola #

FunkciaZolaAstro + lychee
Vstavaná validáciaÁnoNie
Kontrola fragmentovÁnoÁno (s nastavením)
Vyžaduje serverNieÁno
RýchlosťRýchla (pri buildovaní)Pomalšia (za behu)
Kontrola externých odkazovÁnoÁno
Syntax odkazov@/blog/post/index.md/blog/post/

Prístup Zola je elegantnejší – validácia prebieha pri buildovaní bez ďalších nástrojov. Ale s Astro kombinácia rehype pluginov a lychee poskytuje porovnateľnú funkcionalitu. Kompromis je ďalší krok buildu a mierne pomalšia spätná väzba.

Záver #

Validácia fragment odkazov v Astro vyžaduje trochu viac nastavenia ako v Zola, ale je to určite dosiahnuteľné. Kombinácia rehype-slug na generovanie ID nadpisov a lychee s --include-fragments na validáciu mi dáva istotu, že moje interné odkazy a kotvy fungujú správne.

Pekné na tomto prístupe je, že lychee dokáže zachytiť aj iné problémy s odkazmi – ako nefunkčné externé odkazy alebo nesprávne cesty. Stalo sa súčasťou môjho kontrolného zoznamu pred nasadením pre Astro blog. Enjoy!

Odkazy #