Szybka odpowiedź: czy Starlight wystarczy do produkcyjnej dokumentacji w Astro?
- Starlight to gotowy motyw dokumentacji na Astro z wyszukiwaniem, nawigacją, i18n, trybem ciemnym i SEO.
- Treść piszesz w Markdown lub MDX w
src/content/docs/, a katalogi wyznaczają adresy. - Pagefind buduje indeks podczas builda i wyszukuje w przeglądarce, bez backendu i opłat.
- Pagefind obsłuży nawet dziesiątki tysięcy stron, a DocSearch warto rozważyć dla analityki zapytań i zarządzanej usługi. Pagefind również pozwala łączyć indeksy kilku serwisów.
- Ustaw
sitew konfiguracji, bo od niego zależąhreflang, adres kanoniczny i sitemapa. - Komponent przepisany od zera przestaje dostawać aktualizacje ze Starlight.
Co daje Starlight w produkcyjnej dokumentacji Astro
Generalnie skupiam się na Astro w swoich artykułach, bardziej pod kątem treści i różnych optymalizacji, ale w tym wypadku warto pochylić się nad jakąś pomocą dotyczącą dokumentacji. Wiem z doświadczenia, że pewnych problemów nie zauważamy, dopóki nas one same nie znajdą, i tak jest właśnie w tym wypadku.
Starlight to gotowy motyw dokumentacji zbudowany na Astro. Różnica względem stawiania dokumentacji samodzielnie jest zasadnicza i oto co dostajemy w standardzie:
Wyszukiwanie pełnotekstowe. Działające od pierwszego buildu i bez konfiguracji.
i18n, czyli wielojęzyczność z przełącznikiem języka i tłumaczeniami interfejsu.
Nawigacja boczna. Sidebar generowany z konfiguracji albo automatycznie ze struktury.
- Tryb ciemny, wygodny przełącznik motywu wbudowany.
Struktura przyjazna SEO, mamy więc poprawne metadane, semantyczny HTML, szybkość Astro.
Wszystko to dziedziczy atuty Astro: statyczny HTML, zero zbędnego JavaScriptu, dobre . Dokumentacja na Starlight jest szybka domyślnie, bo stoi na frameworku zaprojektowanym wokół wydajności. To jest ta łatwa część — i zajmie Ci kilkanaście minut. Trudniejsze są decyzje, które przychodzą potem: Pagefind czy DocSearch, zakres nadpisywania komponentów i strategia i18n. To o nich jest reszta artykułu.
Krok 1: utworzenie dokumentacji Starlight w Astro
Jedna komenda stawia kompletny projekt dokumentacji z szablonem Starlight:
Po instalacji zależności uruchamiasz serwer deweloperski:
Pod localhost:4321 masz działającą dokumentację z nawigacją i trybem ciemnym — zanim napisałeś choć jedną linijkę własnej treści. W trybie deweloperskim zamiast wyszukiwarki zobaczysz komunikat: Pagefind wymaga indeksu generowanego podczas buildu. Aby sprawdzić wyszukiwanie, zatrzymaj serwer deweloperski i uruchom:
Otwórz adres podglądu podany w terminalu.
Krok 2: treść dokumentacji Starlight w src/content/docs/
Dokumentacja jest w katalogu src/content/docs/ jako pliki Markdown lub , a routing jest oparty na plikach. Oznacza to po prostu, że adresy są wyznaczane przez strukturę katalogów:
Każdy plik ma sterujący tytułem, opisem i miejscem w nawigacji:
Starlight skutecznie zajmie się resztą: layoutem, nawigacją, spisem treści na stronie czy linkami „poprzedni/następny". To bardzo wygodne, a dodatkowo trzeba pamiętać, że frontmatter Starlight jest walidowany schematem Zod. Oznacza to, że zły typ wartości albo brak wymaganego pola zatrzyma build z błędem walidacji, zamiast przemknąć po cichu na produkcję.
Krok 3: wyszukiwanie w Starlight przez Pagefind i kiedy wybrać DocSearch
Jak działa Pagefind bez backendu
Wyszukiwanie to zwykle najtrudniejszy element do dorobienia, a w Starlight działa po pierwszym buildzie, dzięki . Jego model działa zupełnie inaczej niż chmurowe szukajki:
- Indeks generuje się w build time i ląduje jako statyczne pliki w
/pagefind/; przy ustawionymbaseadres zawiera także ten prefiks. - Zapytania wykonują się w przeglądarce przez .
- Brak backendu, brak API key oraz brak opłat za zapytanie.
Na skalowanie ma wpływ pewien bardzo ważny szczegół, mianowicie Pagefind nie ładuje całego indeksu do przeglądarki. Dzieli go na fragmenty i pobiera tylko te, które odpowiadają wpisywanemu zapytaniu. Właśnie dlatego wyszukiwanie działa natychmiast nawet w dużej dokumentacji, choć nie ma żadnego serwera.
- stron, które Pagefind przeszukuje przy transferze poniżej 300 kB
- 10 000stron, które Pagefind przeszukuje przy transferze poniżej 300 kB
- koszt zapytania — indeks jest częścią statycznego builda
- 0 złkoszt zapytania — indeks jest częścią statycznego builda
- typowy transfer wyszukiwania na większości stron, razem z biblioteką
- ~100 kBtypowy transfer wyszukiwania na większości stron, razem z biblioteką
Kiedy zamiast Pagefind wybrać DocSearch
Rozmiar dokumentacji rzadko jest tu problemem. Według twórców Pagefind przeszukuje stronę z 10 000 podstron przy transferze poniżej 300 kB, łącznie z samą biblioteką, a na większości stron jest to bliżej 100 kB. Przy bardzo dużych serwisach rośnie przede wszystkim czas builda i liczba plików indeksu. Jeśli chcesz zawęzić indeks, Pagefind pozwala wykluczyć fragment strony atrybutem data-pagefind-ignore, a Starlight całą stronę polem pagefind: false we frontmatterze.
DocSearch (Algolia) to oficjalna wtyczka Starlight (@astrojs/starlight-docsearch). Ma sens, gdy potrzebujesz analityki zapytań i zarządzanej usługi wyszukiwania. Możesz też ubiegać się o dostęp do darmowego programu DocSearch, otwartego dla publicznej dokumentacji technicznej i blogów technicznych. Tyle tylko, że jest to zewnętrzna usługa, więc trzeba mieć konto, klucze i indeks do utrzymania. Samo wyszukiwanie w kilku serwisach lub wersjach nie wymusza migracji: Pagefind obsługuje łączenie indeksów przez mergeIndex. Wymaga to dodatkowej konfiguracji, a przy różnych domenach także odpowiednich nagłówków CORS.
Krok 4: konfiguracja i nawigacja dokumentacji Starlight
Starlight konfigurujesz jako integrację w astro.config.mjs, właśnie tam ustawiasz adres strony, tytuł, sidebar i języki:
Pole site łatwo pominąć, bo lokalnie wszystko działa bez niego. Na produkcji bez site Starlight nie wygeneruje jednak adresów kanonicznych, sitemapy ani odsyłaczy hreflang.
Sidebar możesz definiować ręcznie (jak wyżej, pełna kontrola nad kolejnością) albo zlecić Starlightowi generowanie automatyczne ze struktury katalogów przez autogenerate:
Autogeneracja oszczędza ręcznego pilnowania listy, ale oddaje kontrolę nad kolejnością. Pozycje układają się alfabetycznie po nazwie pliku, chyba że wymusisz porządek polem sidebar.order we frontmatterze każdej strony. Dobrym rozwiązaniem jest kompromis, czyli hybryda: górne, „wizytówkowe" sekcje definiujesz ręcznie w konkretnej kolejności, a rozrastające się grupy referencyjne zostawiasz autogeneracji.
Krok 5: dostosowanie wyglądu Starlight i component overrides
Nie miej mylnego wrażenia, że skoro Starlight to gotowy motyw, to albo akceptujesz jego wygląd, albo budujesz własną stronę. Dostosowywanie jest warstwowe i większość potrzeb rozwiążesz najniższą, najbezpieczniejszą warstwą.
Zmienne CSS, takie jak kolor akcentu, tło, fonty, promienie. Podpinasz własny arkusz przez
customCssw konfiguracji i nadpisujesz zmienne--sl-color-*. Tym załatwiasz cały branding i 90% zmian wizualnych.Opcje konfiguracji i frontmattera. Logo, linki do profili społecznościowych, link „Edytuj stronę”, data ostatniej zmiany, baner nad treścią (
banner) czy strona startowa (template: splashihero), bez dotykania komponentów motywu.Component overrides. Podmiana wbudowanego komponentu (
Header,Sidebar,PageTitle,Search) własnym. Najsilniejsze narzędzie i jedyne, którym łatwo zrobić sobie krzywdę.
Jak nadpisać komponent Starlight
Override wpina się przez konfigurację, wskazując własny komponent w miejsce wbudowanego:
Owijanie polega na zaimportowaniu domyślnego komponentu i wyrenderowaniu go wewnątrz własnego. Przykład dokłada link do kontaktu obok ikon społecznościowych (w konfiguracji: SocialIcons: './src/components/MySocialIcons.astro'):
Krok 6: wielojęzyczność i hreflang w Starlight
i18n jest wbudowane, więc nie dokładasz osobnej warstwy internacjonalizacji. Definiujesz języki w konfiguracji:
Treść układasz w katalogach per język (src/content/docs/pl/, src/content/docs/en/), a Starlight obsługuje przełącznik języka, tłumaczenia elementów interfejsu i wielojęzyczne wyszukiwanie. To duży skok wygody względem ręcznego konfigurowania routingu i18n na zwykłej stronie Astro.
Nieprzetłumaczone strony i hreflang w Starlight
Po Twojej stronie zostaje jedna decyzja i jedno ustawienie:
- Strony nieprzetłumaczone. Gdy artykuł istnieje po polsku, a nie po angielsku, użytkownik wersji
entrafi na treść w języku zastępczym (fallback dodefaultLocale). Starlight wyświetla wtedy wbudowaną informację o braku tłumaczenia danej strony. To rozwiązanie jest lepsze niż błąd404, jednak mieszanie języków wciąż może być dla użytkownika dezorientujące. Warto więc świadomie decydować, które materiały są na tyle kluczowe, by przetłumaczyć je w całości, a gdzie akceptowalny jest język zapasowy (fallback). hreflangdla SEO. Wielojęzyczna dokumentacja powinna informować Google o powiązaniach między wersjami językowymi przez , inaczej ryzykujesz kanibalizacją i błędnym dopasowaniem języka w wynikach. Starlight sam dodaje do<head>odsyłaczehreflangdo każdej wersji językowej orazx-default, ale tylko wtedy, gdy w konfiguracji Astro ustawiszsite. Bez niego nie powstaną ani adresy kanoniczne, ani odsyłacze. W Next.js te same odsyłacze trzeba zbudować samodzielnie, co opisuję w artykule o hreflangu w Next.js App Router.
Migracja istniejącej dokumentacji do Starlight
Migracja z Docusaurusa i VitePressa na Starlight
W praktyce rzadko zaczynasz od zera, ponieważ częściej masz już dokumentację w Docusaurusie, VitePressie albo zwykłym Markdownie i chcesz ją przenieść na Starlight. Cztery obszary wymagają wtedy szczególnej uwagi:
- Frontmatter — Starlight ma własny schemat (wymagany
title, opcjonalniedescription,sidebar). Pola z innych generatorów (sidebar_position,sidebar_label,id) trzeba zmapować na odpowiedniki Starlight (sidebar.order,sidebar.label,slug) — inaczej po prostu je zignoruje i stracisz kontrolę nad kolejnością w nawigacji. - Komponenty i bloki wyróżnień — Starlight obsługuje
:::note,:::tip,:::cautioni:::danger, także z własnym tytułem (:::tip[Wskazówka]). Składnia nie jest jednak identyczna we wszystkich generatorach. Przy migracji z VitePressa zamień:::infona:::note,:::warningna:::cautionoraz tytuły w formie::: tip Wskazówkana:::tip[Wskazówka]. Kontenery:::detailswymagają osobnego dostosowania. Komponenty Reacta można zachować dzięki integracji@astrojs/react, jeśli są kompatybilne z Astro; przeróbek wymagają zwłaszcza zależności od kontekstu, routingu i innych mechanizmów Docusaurusa. - Linki wewnętrzne i obrazy — inna struktura URL i inne miejsce na pliki statyczne oznaczają, że relatywne linki i ścieżki do obrazów zwykle wymagają korekty. Astro wykrywa m.in. brakujące lokalne obrazy przetwarzane podczas buildu, ale nie wykonuje pełnego audytu wszystkich adresów. Wtyczka społeczności
starlight-links-validatorsprawdza linki wewnętrzne i może zatrzymać build po wykryciu błędu; nie zastępuje kontroli wszystkich obrazów ani odnośników zewnętrznych. - Wersjonowanie — Docusaurus wersjonuje dokumentację w standardzie, a Starlight nie. Jeśli utrzymujesz kilka wersji API, przed migracją sprawdź wtyczkę społeczności
starlight-versionsalbo zaplanuj osobne buildy dla każdej wersji.
Treść korzystająca ze standardowej składni Markdown zwykle przenosi się bez zmian, co jest dobre — gorzej z metadanymi i komponentami, i to one pochłoną najwięcej czasu. Przy większej dokumentacji opłaca się napisać jednorazowy skrypt przepisujący frontmatter i najczęstsze shortcode'y, zamiast przechodzić setki plików ręcznie.
Kiedy wybrać Starlight, a kiedy własną dokumentację w Astro
Starlight, gdy chcesz profesjonalną dokumentację szybko, a Twoje potrzeby wizualne mieszczą się w zmiennych CSS plus najwyżej kilku punktowych overrides. To zdecydowana większość dokumentacji technicznej.
Własna strona Astro, gdy nietypowy layout wymagałby nadpisania rdzenia motywu (nawigacji, wyszukiwarki, struktury strony) albo dokumentacja jest częścią większego produktu o własnym designie i musi się z nim jakoś sensownie połączyć.
Domyślnie zaczynaj od Starlight, a jeśli z czasem okaże się, że potrzebujesz własnego layoutu, przesiadka i tak wyjdzie taniej niż budowanie wszystkiego od zera. Dlaczego? Treść w src/content/docs/ to zwykła kolekcja treści Astro, więc przy przesiadce przebudowujesz głównie layout, a standardowy Markdown zwykle pozostaje bez zmian; rozszerzenia Starlight i osadzone komponenty mogą wymagać dostosowania.


