Starlight i Astro: Produkcyjna dokumentacja w kilkanaście minut

Co dostajesz w standardzie

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 wypadku dokumentacji.

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 Core Web Vitals. 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: granice Pagefind, zakres nadpisywania komponentów i strategia i18n. To o nich jest reszta artykułu.

Krok 1: Utworzenie projektu

Jedna komenda stawia kompletny projekt dokumentacji z szablonem Starlight:

npm create astro@latest -- --template starlight

Po instalacji zależności uruchamiasz serwer deweloperski:

cd moja-dokumentacja
npm run dev

Pod localhost:4321 masz działającą dokumentację z wyszukiwaniem, nawigacją i trybem ciemnym — zanim napisałeś choć jedną linijkę własnej treści.

Krok 2: Treść w src/content/docs/

Dokumentacja jest w katalogu src/content/docs/ jako pliki Markdown lub MDX, a routing jest oparty na plikach. Oznacza to po prostu, że adresy są wyznaczane przez strukturę katalogów:

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

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

---
title: Instalacja
description: Jak zainstalować i skonfigurować projekt.
---
 
## Wymagania
 
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 — Pagefind i jego granice

Jak działa Pagefind bez backendu

Wyszukiwanie to zwykle najtrudniejszy element do dorobienia, a w Starlight działa od razu, dzięki Pagefind. Jego model działa zupełnie inaczej niż chmurowe szukajki:

• Indeks generuje się w build time i ląduje jako statyczne pliki w /_pagefind/.
• Zapytania wykonują się w przeglądarce przez WebAssembly.
• 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 sto czy dwieście stron szuka natychmiast, mimo że nie ma żadnego serwera.

Kiedy Pagefind przestaje wystarczać i wchodzi DocSearch

Są też ograniczenia i te widać dopiero przy dużych, gęstych serwisach technicznych, posiadających tysiące stron z długą treścią. Wtedy sumaryczny rozmiar plików indeksu i czas pierwszego zapytania zaczynają rosnąć. Sytuacja będzie wtedy ulegać stopniowemu pogorszeniu i trzeba mieć na to oko. Masz wtedy dwa rozwiązania: albo ograniczyć zakres indeksowania (Pagefind pozwala wykluczyć fragmenty stron atrybutem data-pagefind-ignore), albo przejść na DocSearch.

DocSearch (Algolia) to oficjalna wtyczka Starlight, bardzo sensowna, jeśli kwalifikujesz się do darmowego programu DocSearch dla open source albo prowadzisz naprawdę duży serwis. Tyle tylko, że jest to zewnętrzna usługa, więc trzeba mieć konto, klucze i indeks do utrzymania.

Krok 4: Konfiguracja i nawigacja

Starlight konfigurujesz jako integrację w astro.config.mjs, właśnie tam ustawiasz tytuł, sidebar i języki:

// astro.config.mjs
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
 
export default defineConfig({
  integrations: [
    starlight({
      title: 'Dokumentacja projektu',
      sidebar: [
        { label: 'Start', link: '/getting-started/' },
        {
          label: 'Przewodniki',
          items: [
            { label: 'Instalacja', link: '/guides/instalacja/' },
            { label: 'Konfiguracja', link: '/guides/konfiguracja/' },
          ],
        },
      ],
    }),
  ],
})

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:

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 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.

• Sloty i propsy komponentów. Drobne wstawki (baner nad treścią, stopka, dodatkowy element w sidebarze) bez dotykania logiki 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:

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

Krok 6: Wielojęzyczność (i18n) i hreflang

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

starlight({
  title: 'Dokumentacja projektu',
  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

Ale dwie decyzje zostają po Twojej stronie i żadna nie jest domyślką:

• 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). To lepsze niż 404, ale mieszany język bywa mylący. Świadomie decyduj, co jest wystarczająco ważne, by przetłumaczyć w całości, a gdzie fallback jest akceptowalny.
• hreflang dla SEO. Wielojęzyczna dokumentacja powinna informować Google o powiązaniach między wersjami językowymi przez hreflang, inaczej ryzykujesz kanibalizacją i błędnym dopasowaniem języka w wynikach. Starlight generuje poprawne lang i strukturę URL-i, ale zadbanie o kompletne, wzajemne odsyłacze hreflang w <head> to część, którą zwykle domykasz sam — analogicznie do tego, co robisz przy i18n w Next.js App Router.

Migracja istniejącej dokumentacji

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. Trzy rzeczy zajmą wtedy najwięcej czasu:

• Frontmatter — Starlight ma własny schemat (wymagany title, opcjonalnie description, sidebar). Pola z innych generatorów (sidebar_position, id) trzeba zmapować na odpowiedniki Starlight (sidebar.order, slug) — inaczej po prostu je zignoruje i stracisz kontrolę nad kolejnością w nawigacji.
• Komponenty i shortcode'y — admonition z Docusaurusa, kontenery :::tip z VitePressa, własne shortcode'y. Starlight ma własne odpowiedniki (np. komponent <Aside>), ale to zamiana jeden-do-jednego, którą trzeba przejść przez treść.
• 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. Zbuduj z włączonym sprawdzaniem martwych linków, żeby złapać je w build, nie po wdrożeniu.

Sama treść w Markdownie 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 Starlight, a kiedy własna strona

• 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. Jeśli z czasem okaże się, że potrzebujesz własnego layoutu, przesiadka i tak wyjdzie taniej niż budowanie wszystkiego od zera. Dlaczego? W większości przypadków Starlight wystarcza.