Starlight 0.39 to kolejna aktualizacja oficjalnego narzędzia Astro do budowy stron dokumentacyjnych. Nie jest to wydanie, które wywraca wszystko do góry nogami. I dobrze. Tym razem zespół Astro skupił się na rzeczach, które w codziennej pracy naprawdę mają znaczenie: bardziej elastycznej nawigacji, drobnych poprawkach w wyglądzie oraz lepszej obsłudze stron wielojęzycznych.
Jeżeli korzystasz ze Starlighta do dokumentacji produktu, panelu pomocy, bazy wiedzy albo technicznego poradnika, ta wersja może ułatwić utrzymanie porządku w treściach. Szczególnie wtedy, gdy dokumentacja zaczyna się rozrastać i prosty układ kategorii przestaje wystarczać.
Czym właściwie jest Starlight?
Starlight to oficjalny pakiet Astro do tworzenia szybkich i dostępnych stron dokumentacyjnych. Można go traktować jako gotowy fundament pod dokumentację techniczną, help center, instrukcje dla użytkowników, poradniki wdrożeniowe albo wewnętrzną bazę wiedzy.
Największa zaleta jest prosta: nie trzeba budować wszystkiego od zera. Starlight daje gotowy układ dokumentacji, wyszukiwarkę, sidebar, obsługę wielu języków, wersję mobilną, dobre podstawy SEO i rozsądnie poukładaną strukturę. Do tego działa na Astro, więc strona może być szybka, lekka i wygodna w utrzymaniu.
To nie jest narzędzie tylko dla dużych projektów open source. Spokojnie sprawdzi się też w firmie, która chce uporządkować instrukcje, opisać produkt, przygotować dokumentację dla klientów albo przenieść wiedzę z plików PDF i rozproszonych notatek do jednego, czytelnego miejsca.
Najważniejsza zmiana: bardziej elastyczny sidebar
Największą nowością w Starlight 0.39 jest bardziej elastyczne generowanie linków w bocznej nawigacji. Sidebar w dokumentacji ma ogromne znaczenie, bo to on decyduje, czy użytkownik szybko znajdzie odpowiednią sekcję, czy zacznie błądzić po stronie.
Starlight od początku potrafił automatycznie generować linki w sidebarze na podstawie katalogów z treścią. To wygodne, zwłaszcza gdy dokumentacja ma wiele podstron. Wcześniej taki automatycznie wygenerowany blok działał jednak bardziej sztywno. Teraz można go swobodniej mieszać z innymi typami linków.
Co to oznacza po ludzku? Możesz mieć jedną grupę w nawigacji, w której część linków jest dodana ręcznie, część generuje się automatycznie z katalogu, a część prowadzi do zewnętrznych zasobów. Bez kombinowania i bez tworzenia sztucznych obejść.
Dlaczego to jest przydatne?
W małej dokumentacji różnica może wydawać się kosmetyczna. Masz kilka stron, kilka kategorii i wszystko jest proste. Problem zaczyna się później, kiedy treści przybywa. Dochodzą poradniki, sekcje API, instrukcje konfiguracji, przewodniki dla różnych użytkowników, strony „start here”, linki do panelu klienta, repozytorium albo pomocy technicznej.
Wtedy nawigacja musi być nie tylko automatyczna, ale też dobrze ułożona. Nie wszystko powinno wpadać do sidebaru w kolejności wynikającej z katalogów. Czasem trzeba dodać ważną stronę wyżej, wyróżnić link do wsparcia, połączyć treści z kilku miejsc albo wstawić link zewnętrzny obok lokalnych stron dokumentacji.
I właśnie tu nowa elastyczność Starlighta ma sens. Daje więcej kontroli nad strukturą, bez rezygnowania z wygody automatycznego generowania linków.
Przykład zastosowania w dokumentacji
Wyobraźmy sobie dokumentację systemu, która ma sekcję „Funkcje”. W tej sekcji chcesz pokazać jedną ręcznie przygotowaną stronę startową, potem automatycznie wygenerowaną listę podstron z katalogu, a na końcu link do zewnętrznego centrum pomocy.
Wcześniej taki układ był mniej naturalny. W Starlight 0.39 można to zrobić czyściej, bo automatycznie generowane linki mogą być częścią tablicy items, obok normalnych linków i linków zewnętrznych.
starlight({
sidebar: [
{
label: 'Funkcje',
items: [
'features-overview',
{ autogenerate: { directory: 'features' } },
{ label: 'Wsparcie', link: 'https://support.example.com' },
],
},
],
})Taki zapis jest czytelniejszy i bardziej przewidywalny. A przy większej dokumentacji to naprawdę ma znaczenie, bo sidebar bardzo szybko potrafi stać się miejscem, w którym zaczyna się bałagan.
Poprawki w stylowaniu
Druga grupa zmian dotyczy wyglądu i zachowania interfejsu. To nie są rzeczy, które użytkownik zawsze zauważy od razu, ale właśnie takie drobiazgi często decydują o tym, czy dokumentacja jest wygodna.
W Starlight 0.39 poprawiono między innymi odstępy w zagnieżdżonych listach. Brzmi mało efektownie, ale w dokumentacji listy są wszędzie: instrukcje krok po kroku, wymagania, opcje konfiguracji, parametry, warianty ustawień. Jeśli takie elementy mają za małe odstępy albo zlewają się ze sobą, tekst staje się męczący.
Poprawiono też stabilność sidebara przy rozwijaniu i zwijaniu grup. Chodzi o ograniczenie przesunięć układu, które pojawiały się w niektórych sytuacjach przy zmianie wysokości i przewijaniu. Niby detal. Ale w dokumentacji takie „skakanie” interfejsu przeszkadza bardziej, niż mogłoby się wydawać.
Lepsze wsparcie dla stron wielojęzycznych
Starlight od początku mocno stawia na dokumentacje wielojęzyczne. W wersji 0.39 pojawiły się kolejne poprawki w tym obszarze, szczególnie ważne dla projektów, które mają kilka wersji językowych i chcą dobrze wypadać w wyszukiwarkach.
Najważniejsza zmiana to lepsze linki alternatywne dla SEO, w tym obsługa x-default. To sygnał dla wyszukiwarek, która wersja strony ma być traktowana jako domyślna, gdy nie ma lepszego dopasowania językowego dla użytkownika.
Dla zwykłej strony firmowej może to brzmieć technicznie, ale przy dokumentacji międzynarodowej ma duże znaczenie. Jeżeli użytkownik wchodzi z kraju lub języka, dla którego nie masz osobnej wersji, wyszukiwarka powinna wiedzieć, gdzie go najlepiej skierować.
Lepsza czytelność dla języków chińskiego i japońskiego
W aktualizacji pojawiła się też poprawa układu tekstu dla dokumentacji w językach chińskim i japońskim. Starlight wykorzystuje tutaj właściwość CSS text-autospace, która pomaga automatycznie dodawać odstępy między znakami CJK a znakami spoza tego zestawu.
Dla polskiego użytkownika nie będzie to najbardziej odczuwalna zmiana. Ale dla projektów globalnych, które prowadzą dokumentację w kilku językach, takie usprawnienia są ważne. Dokumentacja ma być czytelna nie tylko po angielsku.
Aktualizacja i18next
W Starlight 0.39 zaktualizowano również i18next, czyli bibliotekę odpowiedzialną za część mechanizmów lokalizacji. Przejście z wersji 23 do 26 to krok techniczny, ale istotny dla utrzymania projektu w dobrej kondycji.
Aktualne zależności oznaczają mniej problemów w przyszłości, lepszą kompatybilność i łatwiejsze utrzymanie dokumentacji. To nie jest funkcja, którą pokażesz klientowi na zrzucie ekranu, ale przy dłużej rozwijanym projekcie takie rzeczy po prostu trzeba mieć pod kontrolą.
Jak zaktualizować Starlight?
Aktualizacja istniejącej strony opartej o Starlight może zostać wykonana przez oficjalne narzędzie aktualizacyjne Astro. Najprostsza komenda wygląda tak:
npx @astrojs/upgradeTo polecenie aktualizuje Starlight, Astro i używane integracje. Po aktualizacji warto oczywiście uruchomić build, sprawdzić stronę lokalnie i upewnić się, że dokumentacja działa poprawnie. Przy większych projektach dobrze też przejrzeć changelog, zwłaszcza jeśli konfiguracja sidebara była mocno rozbudowana.
Czy Starlight 0.39 zmienia coś dla firm?
Dla firm najważniejsze jest to, że Starlight dojrzewa jako narzędzie do dokumentacji. To już nie jest tylko ładny szablon na kilka stron instrukcji. To coraz pełniejszy system do budowy uporządkowanej, szybkiej i dostępnej bazy wiedzy.
Jeżeli firma ma produkt techniczny, aplikację SaaS, oprogramowanie, system wewnętrzny albo rozbudowaną usługę, dobra dokumentacja potrafi mocno odciążyć support. Użytkownik szybciej znajduje odpowiedź, zespół dostaje mniej powtarzalnych pytań, a proces wdrożenia klienta jest spokojniejszy.
Starlight dobrze pasuje do takich zastosowań, bo nie wymaga ciężkiego CMS-a. Treści mogą być trzymane w plikach, wersjonowane razem z kodem i wdrażane jak normalny projekt Astro. Dla zespołów technicznych to często wygodniejsze niż klikanie w panelu administracyjnym.
Dokumentacja jako część doświadczenia klienta
Dokumentacja bywa traktowana po macoszemu. Najpierw robi się stronę, potem produkt, potem panel, a instrukcje „kiedyś się dopisze”. Efekt jest przewidywalny: użytkownicy pytają o te same rzeczy, support odpowiada ręcznie, a wiedza jest rozrzucona po mailach, PDF-ach i wiadomościach na Slacku.
Dobrze zrobiona dokumentacja rozwiązuje ten problem. Nie zastępuje kontaktu z człowiekiem, ale daje klientowi pierwsze miejsce, do którego może zajrzeć. Jeśli jest szybka, czytelna i dobrze poukładana, realnie poprawia odbiór całej usługi.
Starlight 0.39 idzie właśnie w tym kierunku. Poprawia nie tyle efekt „wow”, ile codzienną pracę z dokumentacją. A to często ważniejsze niż kolejna duża funkcja.
Kiedy warto użyć Starlight?
Starlight ma sens tam, gdzie treść musi być uporządkowana, łatwa do przeszukiwania i wygodna do czytania. Szczególnie dobrze sprawdzi się przy dokumentacji technicznej, instrukcjach produktu, bazie wiedzy, dokumentacji API, poradnikach wdrożeniowych oraz materiałach dla klientów lub pracowników.
To dobry wybór, jeśli dokumentacja ma być szybka, lekka i nie chcesz budować jej na WordPressie z kolejnym motywem i zestawem wtyczek. Astro i Starlight dają bardziej techniczne, ale też bardziej kontrolowane podejście. Mniej przypadkowych zależności, więcej porządku.
Starlight 0.39 — mała aktualizacja, ale w dobrym kierunku
Starlight 0.39 nie próbuje robić rewolucji. To raczej spokojne dopracowanie narzędzia, które już teraz dobrze nadaje się do tworzenia dokumentacji. Elastyczniejszy sidebar ułatwia układanie większych treści, poprawki stylowania zwiększają czytelność, a zmiany w obsłudze wielu języków pomagają projektom, które wychodzą poza jedną wersję językową.
Dla właściciela firmy najważniejszy wniosek jest prosty: jeżeli potrzebujesz dokumentacji, centrum pomocy albo bazy wiedzy, nie musisz od razu sięgać po ciężki CMS. Starlight na Astro może dać szybsze, czystsze i spokojniejsze rozwiązanie.
Dokumentacja na Astro w praktyce
W Astrofy tworzymy szybkie strony oparte o Astro i Tailwind, ale ten sam kierunek dobrze sprawdza się też przy dokumentacji. Jeżeli masz produkt, usługę techniczną, system B2B albo wewnętrzną bazę wiedzy, można zbudować dla tego osobny, lekki serwis dokumentacyjny oparty o Starlight.
Taka dokumentacja może działać szybko, mieć dobrą strukturę SEO, wygodną nawigację i prosty proces rozwoju. Bez ciężkiego panelu, bez bazy danych i bez przypadkowych wtyczek. Po prostu porządna baza wiedzy, która pomaga użytkownikom znaleźć odpowiedź, zanim napiszą do supportu. Porozmawiajmy o tym, jak takie rozwiązanie mogłoby wyglądać u Ciebie.