Szybka odpowiedź: jak zbudować typowany blog w Astro na Content Collections i Zod?
- Zdefiniuj kolekcję z loaderem i jednym schematem Zod dla wpisów oraz autorów.
- Stronę wpisu generuj w
getStaticPathsz tego samego modelu danych. - Szkice i przyszłe daty filtruj jedną wspólną funkcją dla listy, tras i kanałów dystrybucji.
- Brakujące pole albo błędna data zatrzymają build, zamiast trafić na produkcję.
- Typy sprawdzaj osobno przez
astro checkw CI i testuj przypadki brzegowe, np. uszkodzone referencje do autora.
Co dają i czym są Content Collections w blogu Astro?
Content Collections stanowią powiązane grupy wpisów, ładowane ze wskazanego źródła i przekazywane do szablonów za pośrednictwem dedykowanego API Astro. Wykorzystany loader glob() odpowiada za odczyt niezależnych plików, podczas gdy file() potrafi rozbić pojedynczy plik JSON na osobne rekordy. Zadeklarowany schemat Zod precyzuje oczekiwaną strukturę i typy pól, na podstawie których Astro automatycznie wyprowadza statyczne typy dla właściwości post.data.
Dla bloga najważniejsza korzyść to jedno miejsce definiujące kontrakt redakcyjny, ponieważ przykładowo, jeśli karta, artykuł i RSS korzystają z tego samego pola description, brak opisu można łatwo wykryć przed publikacją. Zapobiega to konieczności utrzymywania trzech osobnych parserów nagłówków frontmatter. Warto jednak pamiętać o ograniczeniach samej walidacji, ponieważ nawet poprawny składniowo ciąg znaków może przecież zawierać literówki, merytoryczne błędy czy treść skopiowaną z innego wpisu – schemat nie zweryfikuje jakości danych.
| Potrzeba | Właściwy mechanizm |
|---|---|
| Wymagany tytuł i poprawna data | Schemat Zod |
| Podpowiedzi pól w kodzie szablonu | Typy wygenerowane przez Astro |
| Wykrycie nieistniejącego pola użytego w kodzie | astro check |
| Ukrycie szkiców i zaplanowanych wpisów | Filtr danych używany w trasach i listach |
| Czytelny artykuł oraz poprawność faktów | Redakcja i weryfikacja źródeł |
Założenia i pliki przykładu
Przykład jest przeznaczony dla Astro 7, które korzysta z Zod 4 i importu z z astro/zod. Zachowaj konfigurację astro/tsconfigs/strict oraz wersję Node obsługiwaną przez tę linię Astro, co najmniej 22.12.0. Jeżeli dopiero zakładasz projekt, zacznij od poradnika o pierwszej stronie w Astro. Różnice migracyjne opisuje przewodnik migracji do Astro 7, a najważniejsze zmiany tej wersji omawiam w przeglądzie Astro 7.
Zbudujemy dwa adresy, czyli /blog/ z listą i /blog/pierwszy-wpis/ z artykułem. Plik konfiguracji leży bezpośrednio w src i nie będziemy używać tu starszej konwencji src/content/config.ts z type: 'content'. Podczas aktualizacji wyodrębniłem poniższe pliki do osobnego projektu z Astro 7.3.2 i TypeScriptem 6.0.3. astro check i astro build przeszły poprawnie, sprawdziłem także wariant MDX z integracją 8.0.1 oraz błędne dane opisane w sekcji testów.
Zaczynamy od Markdownu, żeby sam blog nie wymagał komponentów UI ani dodatkowych integracji. Wzorzec loadera obejmie też .mdx, ale przed dodaniem pierwszego takiego pliku zainstaluj zgodne z Astro 7 @astrojs/mdx w wersji 8 i zarejestruj mdx() w integrations w astro.config.mjs.
Od Astro 7 pliki .md i .mdx domyślnie przetwarza Sätteri, więc jeśli korzystasz z pluginów remark lub rehype, doinstaluj @astrojs/markdown-remark, żeby zachować dotychczasowy pipeline, albo przenieś pluginy na Sätteri. Osadzanie komponentów opisuję niżej, w części o MDX w kolekcji Astro.
Jeden schemat Zod dla wpisów i autorów
Poniższa konfiguracja stanowi wspólny fundament dla całego przykładu. Schemat wymusza redakcyjne limity długości dla tytułu i opisu, unifikuje tagi w ramach jednej listy oraz definiuje pole author jako relację do osobnej kolekcji. Warto zauważyć, że każdy nowy wpis traktowany jest domyślnie jako wersja robocza — jego oficjalna publikacja wymaga więc jawnego ustawienia draft: false.
Limity 100 i 200 znaków oczywiście nie są wymogiem Google, ale umownymi wartościami przyjętymi w redakcji, które pozwalają ograniczyć przypadkowo długie pola. Oczywiście trzeba pamiętać, że Google nie publikuje limitów znaków dla tytułu i opisu, a w wynikach może dobrać inny fragment strony jako snippet. Z kolei data ma tu postać pełnego timestampa zapisanego jako string i najpierw walidujemy sam format tekstu, a dopiero po pozytywnej weryfikacji przekształcamy go w obiekt Date. To bardziej jednoznaczny kontrakt niż samo z.coerce.date(), które dopuszcza szerszy zestaw konwersji. Poza tym nie odrzucamy przyszłych dat, ponieważ przydadzą się do planowania publikacji.
Metoda z.object() domyślnie usuwa nieznane pola z wyniku parsowania i taka jest jej rola, ale nie wyłapie automatycznie literówki w nazwie opcjonalnej metadanej. Jeżeli zespół redakcyjny wymaga rygorystycznego odrzucania wszystkich nieoczekiwanych kluczy, warto rozważyć zastosowanie z.strictObject(), pamiętając jednak przy tym o wcześniejszej weryfikacji pól wstrzykiwanych automatycznie przez używany loader lub integracje Astro.
Frontmatter, który przechodzi tę walidację
W pierwszej kolejności zapisz profil w pliku src/content/authors.json. Unikalny klucz id służy do identyfikacji wpisu przez loader file() oraz tworzenia relacji do autora w pozostałych kolekcjach.
Następnie dodaj src/content/blog/pierwszy-wpis.md. Ten opis spełnia zadany limit, data zawiera strefę, a autor odpowiada ID w JSON-ie.
Jednolity schemat metadanych pozwala przechwycić brakujące lub błędne pola jeszcze przed oficjalną publikacją artykułu. Sama treść wpisu zaczyna się od nagłówka drugiego poziomu (##), ponieważ główny nagłówek <h1> generowany jest automatycznie przez szablon na podstawie metadanych. W ten sposób zapobiegamy powstawaniu podwójnych znaczników H1 na stronie.
Nazwa pliku (np. pierwszy-wpis.md) służy w tym loaderze do wygenerowania identyfikatora pierwszy-wpis. Należy pamiętać, że ID definiuje strukturę danych, podczas gdy ostateczny URL kształtuje się w warstwie routingu. Zmiana nazwy pliku na produkcji zmienia ten identyfikator, a w konsekwencji adres wpisu — dlatego po publikacji taka zmiana wymaga zaplanowania odpowiedniego przekierowania. W bardziej rozbudowanych architekturach logikę tworzenia ID można dostosować za pomocą funkcji generateId w loaderze.
Szkice i przyszłe publikacje pod kontrolą
Wszystkie publiczne widoki powinny używać tej samej funkcji pobierania wpisów. Poniższy helper odrzuca szkice, pomija przyszłe daty i sortuje od najnowszych, a w wypadku jednakowych datach porządkuje wyniki według ID.
W przypadku witryny statycznej ostateczny wynik renderowania zostaje utrwalony w momencie kompilacji. W związku z tym samo nadejście wyznaczonej daty nie spowoduje automatycznej publikacji wpisu, więc jeśli artykuł ma ukazać się jutro o 9:00, musisz zaplanować przebudowanie oraz ponowne wdrożenie aplikacji po tej godzinie. Kanał RSS i mapa witryny powinny opierać się na tym samym mechanizmie filtrowania, przy czym integracje generujące sitemapę na podstawie gotowych ścieżek wyjściowych muszą uwzględniać wyłącznie faktycznie zbudowane adresy. Pamiętaj również, że wersja robocza nadal pozostaje częścią kolekcji. Flaga draft: true nie zwalnia pliku z wymogów walidacji Zod i w związku z tym błędne pola w szkicu nadal zablokują proces synchronizacji. Wreszcie, ochrona poufnych materiałów wymaga ścisłej kontroli repozytorium oraz artefaktów wyjściowych.
Generowanie strony i rozwiązanie referencji autora
W src/pages/blog/[...id].astro pobieramy wpisy, tworzymy trasy i przekazujemy dane przez props. Typ CollectionEntry<'blog'> opisuje props szablonu, a getEntry() pobiera profil wskazany referencją.
To kompletny, prosty dokument, bez zależności od niepokazanego layoutu. W projekcie z istniejącym layoutem przenieś do niego <html> i <head>, zachowując jawnie typowane propsy. reference('authors') zmienia identyfikator w obiekt wskazujący kolekcję i wpis. Bezpośrednie sprawdzanie powiązania z polem author zablokuje wdrożenie w przypadku braku profilu danego twórcy. Sprawdzian ten omija jednak autorów przypisanych do szkiców, ponieważ niepublikowane treści nie trafiają do funkcji getStaticPaths. Kompletnie spójny audyt relacji wymaga przejrzenia całej kolekcji wpisów przed odfiltrowaniem wersji roboczych. Warto też dodać, że Astro 7 zgłasza w logu błąd nieprawidłowej referencji także dla szkiców, ale nie przerywa przez to builda. We wcześniejszych wersjach przerywał.
Z kolei nazwa parametru jest dowolna, tyle że musi być spójna. Nazewnictwo pliku routingu wymusza strukturę parametrów: [...id].astro wymaga dostarczenia params.id, a [...slug].astro — params.slug. Użycie składni z wielokropkiem pozwala na bezproblemową obsługę zagnieżdżonych ścieżek. Warto jednak pamiętać, że o ostatecznym kształcie adresu kanonicznego decyduje architektura loadera oraz zmapowana logika, a nie samo wykorzystanie klucza id.
Lista artykułów bez drugiej konfiguracji
Strona listy używa tego samego helpera. Nie powielamy w niej schematu ani reguł publikacji.
Na tym etapie działają lista, publiczny artykuł, autor oraz filtrowanie publikacji. To wystarczająca baza do dodania stylów i kolejnych wpisów. Rozwijaj model przez rozszerzanie istniejącego schematu, aby przy dodawaniu np. powiązanych artykułów nie usunąć przypadkiem pola draft używanego przez szablony.
Komponenty w treści: MDX w kolekcji Astro
MDX dodaje do Markdownu dwie rzeczy: komponenty w treści i importy na początku pliku. Po instalacji integracji (npx astro add mdx) te same wpisy przechodzą przez schemat kolekcji, a w treści możesz użyć ramki z ostrzeżeniem albo interaktywnego kalkulatora:
Komponent React dopiero, gdy pojawi się w widoku, a reszta wpisu zostaje statycznym HTML-em. W Astro nie dodajesz 'use client'; interaktywność włączasz dyrektywą client:* w miejscu użycia. Komponent, który w trakcie renderowania sięga po window albo document, przerwie build przy client:visible, bo Astro renderuje go również na serwerze. Wtedy użyj , pamiętając, że jego treści nie będzie w HTML-u do czasu hydratacji, więc nie nadaje się do treści ważnej dla SEO. Najczęstszy błąd z prostymi komponentami jest prozaiczny: komponent czyta prop variant, a artykuł podaje type, więc ramka zawsze dostaje wartość domyślną.
Tytułu nie powtarzaj w treści MDX. Szablon i tak renderuje <h1>{post.data.title}</h1>, a druga kopia w pliku łatwo się rozjedzie z frontmatterem.
Standardowe elementy możesz podmienić na własne komponenty: nagłówki z kotwicami, linki zewnętrzne z rel="noopener" albo obrazy optymalizowane przez astro:assets. Astro nie nakłada takiej mapy globalnie, więc przekazujesz ją w szablonie wpisu, który renderuje wszystkie artykuły:
Obrazy w MDX importuj i wstawiaj przez <Image> z astro:assets, a nie surowy <img>. Astro wygeneruje wtedy formaty WebP lub AVIF, warianty do srcset i jawne wymiary, które chronią przed . Przy kilkudziesięciu wpisach z kilkoma obrazami każdy to jedna z największych oszczędności transferu w całym blogu.
Walidacja Zod i TypeScript w CI
Walidacja schematów kolekcji wykonuje się podczas synchronizacji treści — m.in. w trakcie uruchamiania astro dev oraz tworzenia pakietu przez astro build. O ile loader bazujący na plikach na bieżąco obserwuje zmiany w lokalnym systemie w trybie deweloperskim, o tyle integracja z zewnętrznym headless CMS wymaga własnej strategii odświeżania danych. Nie należy zakładać, że modyfikacja wpisu w zewnętrznym panelu automatycznie wywoła przebudowę strony bez skonfigurowanych webhooków lub mechanizmu rewalidacji.
astro build nie zastępuje kontroli typów. Zainstaluj @astrojs/check i typescript@6, a w CI uruchom:
Wersja TypeScriptu ma tu znaczenie, ponieważ TypeScript 7 z natywnym kompilatorem nie udostępnia jeszcze API, z którego korzysta astro check, więc polecenie kończy się błędem. @astrojs/check 0.9.10 obsługuje TypeScript 5 i 6, dlatego instalujemy szóstkę.
Polecenie astro check wykonuje analizę statyczną kodu w oparciu o wygenerowane typy kolekcji, dzięki czemu środowisko programistyczne może bez problemu podpowiadać właściwości, takie jak post.data.title. Należy jednak pamiętać, że bieżąca walidacja składni YAML bezpośrednio w plikach Markdown leży po stronie rozszerzeń edytora. Jeśli po modyfikacji schematu Zod typy TypeScript nie aktualizują się automatycznie, uruchom polecenie astro sync i zrestartuj serwer językowy w swoim IDE. Pamiętaj jednak, że udana kompilacja zapobiegnie błędnemu wdrożeniu tylko wtedy, gdy Twój pipeline CI/CD rygorystycznie uzależnia publikację od powodzenia tego etapu. Poniższe scenariusze testowe warto przeprowadzić na kopii pliku, ponieważ dają one znacznie większą pewność niż zwykła weryfikacja wizualna w przeglądarce.
| Zmiana testowa | Oczekiwany wynik |
|---|---|
Usunięcie title albo opis krótszy niż 50 znaków | Błąd walidacji kolekcji |
date: 'jutro rano' | Błąd formatu daty |
tags: [Astro] zamiast tags: [astro] | Błąd wartości spoza enum |
draft: true albo data daleko w przyszłości | Brak trasy artykułu i linku na liście |
| Nieistniejący autor publicznego wpisu | Build zatrzymany podczas rozwiązywania referencji |
post.data.titel w szablonie | Błąd wykryty przez astro check |
| Usunięcie profilu autora szkicu | Potrzebny osobny audyt relacji, jeśli chcesz blokować również takie zmiany |
Kiedy rozszerzyć kolekcję o CMS, obrazy lub dane live?
Przy kilku autorach JSON jest prosty do przeglądu w Gicie. Gdy redakcja potrzebuje panelu, uprawnień i obiegu akceptacji, rozważ headless CMS w Astro. Sprawdź, czy wybrany pakiet faktycznie udostępnia loader Content Layer, czy tylko klienta API albo komponenty. API i wersje loaderów zależą od dostawcy. Dla lokalnych obrazów użyj helpera image() w funkcji schematu, jeżeli chcesz korzystać z metadanych i przetwarzania obrazów Astro. Zwykły z.string() sprawdza tekst, nie istnienie pliku. Dla zewnętrznych adresów waliduj URL i dozwolony protokół; samo startsWith('/') przepuści także adres zaczynający się od //.
Build-time collections pasują do treści aktualizowanych wraz z wdrożeniem. Live Content Collections pobierają dane podczas obsługi zapytania do kolekcji i wymagają świadomej obsługi błędów oraz cache. W Astro 7 loader danych live może dołączyć do wyniku podpowiedź dla cache, czyli tagi do unieważniania i czas ostatniej modyfikacji. Aby dane zmieniały się pomiędzy wizytami bez przebudowy strony, potrzebujesz renderowania na żądanie i odpowiedniego adaptera. Nie są konieczne do tego bloga; szerszy kontekst znajdziesz w omówieniu Astro 6.
Co Content Collections zmieniają w SEO?
Co do zasady spójne dane ułatwiają generowanie tytułów, opisów, RSS i danych strukturalnych, pomagając pośrednio w indeksacji. Szablon musi oczywiście osadzać metadane bezpośrednio w kodzie HTML, choć o ostatecznym uwzględnieniu konkretnych adresów w indeksie i tak decydują nieubłagane algorytmy Google. Przed samą publikacją upewnij się, że skonfigurowałeś docelową domenę, wdrożyłeś spójną politykę adresów kanonicznych oraz zweryfikowałeś poprawność mapy witryny i kodów odpowiedzi HTTP. Tworząc dane strukturalne BlogPosting, dbaj o to, by dokładnie odzwierciedlały widoczną treść artykułu. Ścieżki do obrazów zawsze przekształcaj w adresy bezwzględne za pomocą konstruktora new URL(path, site), co zapobiegnie błędom podwójnego doklejania domeny do istniejącego adresu URL. Dodatkowo, jeśli osadzasz JSON-LD przy użyciu dyrektywy set:html, zabezpiecz proces serializacji przed ryzykiem przedwczesnego zamknięcia znacznika <script> przez niezweryfikowane znaki (np. zamieniając < na sekwencję \u003c).
Szczegóły znajdziesz w poradniku o technicznym SEO w Astro. Schemat powinien wspierać te mechanizmy, a jego limity wynikać z potrzeb publikacji. Google nie określa preferowanej liczby słów. Skracaj powtarzalny kod po to, żeby czytelnik łatwiej wdrożył rozwiązanie, nie po to, by osiągnąć domniemany współczynnik tekstu do kodu.


