Przejdź do treści

Starlight i Astro: produkcyjna dokumentacja w kilkanaście minut

Maciej Sala

Founder StriveLab

10 min czytaniaAktualizacja

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 site w 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:

Code
npm create astro@latest -- --template starlight

Po instalacji zależności uruchamiasz serwer deweloperski:

Code
cd moja-dokumentacja
npm run dev

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:

Code
npm run build
npm run preview

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:

Code
src/content/docs/
├── index.mdx              → /
├── getting-started.md     → /getting-started
└── guides/
    ├── instalacja.md      → /guides/instalacja
    └── konfiguracja.md    → /guides/konfiguracja

Każdy plik ma sterujący tytułem, opisem i miejscem w nawigacji:

Code
---
title: Instalacja
description: Jak zainstalować i skonfigurować projekt.
---
 
## Wymagania dla produkcyjnej dokumentacji Starlight
 
Treść piszesz w zwykłym Markdownie, a w plikach `.mdx` możesz
dodatkowo osadzać komponenty.

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 ustawionym base adres 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:

Code
// astro.config.mjs
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
 
export default defineConfig({
  // adres produkcyjny: od niego zależą canonical, sitemapa i hreflang
  site: 'https://docs.example.com',
  integrations: [
    starlight({
      title: 'Dokumentacja projektu',
      sidebar: [
        { label: 'Start', link: '/getting-started/' },
        {
          label: 'Przewodniki',
          items: [
            { label: 'Instalacja', link: '/guides/instalacja/' },
            { label: 'Konfiguracja', link: '/guides/konfiguracja/' },
          ],
        },
      ],
    }),
  ],
})

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:

Code
sidebar: [
  { label: 'Start', link: '/getting-started/' },
  { label: 'Przewodniki', autogenerate: { directory: 'guides' } },
]

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 customCss w 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: splash i hero), 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:

Code
starlight({
  title: 'Dokumentacja projektu',
  components: {
    // podmieniamy tylko nagłówek, reszta motywu bez zmian
    Header: './src/components/MyHeader.astro',
  },
})

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'):

Code
---
// src/components/MySocialIcons.astro
import Default from '@astrojs/starlight/components/SocialIcons.astro'
---
 
<a href="mailto:kontakt@example.com">Kontakt</a>
<Default><slot /></Default>

Krok 6: wielojęzyczność i hreflang w Starlight

i18n jest wbudowane, więc nie dokładasz osobnej warstwy internacjonalizacji. Definiujesz języki w konfiguracji:

Code
starlight({
  title: 'Dokumentacja projektu',
  // wymaga `site` w defineConfig, tak jak w kroku 4
  defaultLocale: 'pl',
  locales: {
    pl: { label: 'Polski', lang: 'pl' },
    en: { label: 'English', lang: 'en' },
  },
})

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 en trafi na treść w języku zastępczym (fallback do defaultLocale). Starlight wyświetla wtedy wbudowaną informację o braku tłumaczenia danej strony. To rozwiązanie jest lepsze niż błąd 404, 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).
  • hreflang dla 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łacze hreflang do każdej wersji językowej oraz x-default, ale tylko wtedy, gdy w konfiguracji Astro ustawisz site. 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, opcjonalnie description, 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, :::caution i :::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ń :::info na :::note, :::warning na :::caution oraz tytuły w formie ::: tip Wskazówka na :::tip[Wskazówka]. Kontenery :::details wymagają 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-validator sprawdza 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-versions albo 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.

Ultraszybkie projekty, łączące lekkość ze skalowalnością.
Astro

Często zadawane pytania

Czym jest Starlight?

Starlight to gotowy, w pełni wyposażony motyw dokumentacji zbudowany na Astro. Dostarcza wyszukiwanie pełnotekstowe (Pagefind), wielojęzyczność (i18n), nawigację boczną, tryb ciemny i strukturę przyjazną SEO. Stawiasz projekt jedną komendą i piszesz treść w Markdown/MDX.

Jak wyszukiwanie w Starlight działa bez backendu?

Starlight używa Pagefind, czyli wyszukiwarki dla stron statycznych. Indeks generuje się w build time i serwowany jest jako statyczne pliki w katalogu /pagefind/ (z prefiksem base, jeśli go ustawisz), a zapytania wykonują się w przeglądarce przez WebAssembly. Brak serwera, brak API key, brak opłat za zapytanie, a dodatkowo działa wielojęzycznie.

Jak duża może być dokumentacja, zanim Pagefind zacznie zwalniać?

Rozmiar dokumentacji rzadko jest ograniczeniem. Pagefind pobiera nie cały indeks, ale tylko fragmenty potrzebne do konkretnego zapytania, dlatego według twórców przeszukuje stronę z 10 000 podstron przy transferze poniżej 300 kB, łącznie z samą biblioteką. DocSearch (Algolia) warto rozważyć, gdy potrzebujesz analityki zapytań lub zarządzanej usługi. Pagefind także pozwala łączyć indeksy kilku serwisów lub wersji przez mergeIndex; przy różnych domenach wymaga to konfiguracji CORS.

Czy da się dostosować wygląd i komponenty Starlight?

Tak, na trzech poziomach: zmienne CSS (kolory, akcent, fonty) dla brandingu, opcje konfiguracji i frontmattera (logo, baner, strona startowa) dla drobnych zmian oraz component overrides, czyli nadpisanie wbudowanych komponentów własnymi (Header, Sidebar, PageTitle). Override jest potężny, ale komponent przepisany od zera przestaje dostawać aktualizacje ze Starlight, więc rób to punktowo.

Kiedy Starlight zamiast własnej strony dokumentacji?

Starlight wygrywa, gdy chcesz profesjonalną dokumentację szybko i nie chcesz budować nawigacji, wyszukiwania i i18n od zera. Własną stronę warto budować dopiero, gdy potrzebujesz nietypowego layoutu albo głębokiej integracji z resztą aplikacji, której motyw nie obsłuży nawet przez overrides. Dla większości dokumentacji technicznej Starlight to szybsza droga.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat Astro

Czytaj dalej

Zobacz więcej wpisów
Czy warto zamienić WordPressa na Astro w projekcie?

WordPress i Astro nie stanowią bezpośrednich alternatyw. Pierwszy z nich to kompleksowy system CMS ze wbudowanym panelem administracyjnym, relacyjną bazą danych oraz rozbudowanym ekosystemem wtyczek, podczas gdy Astro pozostaje nowoczesnym frameworkiem do budowy frontendu. Ostateczny wybór dotyczy zatem całej architektury rozwiązania, czyli sposobu renderowania stron, modelu edycji treści, strategii integracji oraz podziału odpowiedzialności za późniejsze utrzymanie systemu.

Maciej Sala

Maciej Sala

Founder StriveLab

Framework Astro w praktyce: przewodnik od architektury po utrzymanie

Strona internetowa może mieć świetny wynik PageSpeed, a mimo to wciąż mieć różne problemy, poczynając od blokowania publikacji artykułów, a kończąc na gubieniu zapytania z formularza. Stworzyłem ten przewodnik, by sprawnie prowadził przez wybór technologii, migrację, model treści, rendering, SEO i testy, aż po wdrożenie i utrzymanie. Szczegółowe rozwiązania znajdziesz w materiałach przypisanych do poszczególnych etapów.

Maciej Sala

Maciej Sala

Founder StriveLab

Pierwszy projekt w Astro 7 od instalacji do wdrożenia

W Astro jedna komenda tworzy projekt z gotowymi skryptami do pracy lokalnej i budowania strony. W tym przewodniku przygotujesz stronę w Astro 7, poznasz strukturę katalogów, sprawdzisz wynik produkcyjnego builda i skonfigurujesz pierwsze wdrożenie.

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G