Docusaurus, generator dokumentacji od Mety

Docusaurus, generator dokumentacji od Mety

Docusaurus buduje statyczną stronę dokumentacji z plików Markdown i MDX, używając Reacta jako warstwy szablonów. Bieżąca wersja @docusaurus/core to 3.10.2 z 10 lipca 2026 roku, licencja MIT. Wyszukiwarki w komplecie nie ma i to jest pierwsza decyzja, którą trzeba podjąć przed wdrożeniem, a nie po nim.

Czym Docusaurus jest, a czym nie

Docusaurus bierze katalog z plikami Markdown i MDX, dokłada do nich pasek nawigacji, boczne menu, przełącznik motywu, stronę bloga i generuje z tego statyczne pliki HTML. Wynik wrzucasz na dowolny hosting plików statycznych, na przykład na Netlify albo GitHub Pages. Serwera aplikacyjnego nie potrzebujesz.

Warstwą szablonów jest React. To nie jest szczegół implementacyjny, tylko konsekwencja, którą poniesiesz. Opublikowany pakiet 3.10.2 deklaruje peerDependencies na react w wersji ^18.0.0 || ^19.0.0 oraz react-dom w tych samych wersjach, a engines.node wymaga Node co najmniej 20.0. Każda strona, którą chcesz napisać poza Markdownem, jest komponentem Reacta w src/pages. Każda zmiana wyglądu wykraczająca poza zmienne CSS oznacza swizzling, czyli podmianę komponentu motywu na własną kopię.

Czego Docusaurus nie robi, jest równie ważne. Nie ma wyszukiwania po stronie serwera, bo nie ma serwera. Nie generuje dokumentacji API z kodu źródłowego, do tego potrzebujesz osobnej wtyczki albo generatora, który wypluje pliki Markdown. Nie zarządza uprawnieniami, więc dokumentacja za logowaniem to problem hostingu, nie generatora. Nie jest też biblioteką komponentów, którą pokażesz projektantom, do tego służy Storybook.

Zakres wbudowanych funkcji obejmuje natomiast trzy rzeczy, których konkurencja często nie ma w rdzeniu: wersjonowanie dokumentacji, tłumaczenia i blog. Te trzy pozycje decydują o tym, kiedy Docusaurus wygrywa.

Wersja, licencja i tempo wydań

Licencja jest przypadkiem wzorcowym i sprawdzenie jej zajmuje trzy minuty. W repozytorium facebook/docusaurus w gałęzi głównej leży plik LICENSE z tekstem MIT i nagłówkiem „Copyright (c) Facebook, Inc. and its affiliates”. Pliku LICENSE.md nie ma, więc nie trzeba zgadywać, który z nich obowiązuje. Pole license w rejestrze npm dla @docusaurus/core ma wartość MIT. Rozpakowana paczka core-3.10.2.tgz zawiera plik package/LICENSE z tym samym tekstem MIT, a obok niego 122 pliki .js i około 1,2 MB rzeczywistego kodu. Trzy źródła, jedna odpowiedź, żadnych atrap. Pakiety towarzyszące zachowują się tak samo: @docusaurus/preset-classic, @docusaurus/theme-search-algolia, @docusaurus/faster i create-docusaurus mają wersję 3.10.2 i licencję MIT.

Pytanie o Docusaurusa 4 wymaga precyzyjnej odpowiedzi, bo od niej zależy, czy zaczynać projekt teraz. W rejestrze npm nie ma żadnej wersji zaczynającej się od 4., w żadnym kanale. Znaczniki dystrybucyjne wyglądają tak: latest to 3.10.2, next to 3.0.0-rc.1, alpha to 3.9.2-alpha.4, canary to 3.10.1-canary-6655 z 4 czerwca 2026 roku. Znacznik next został przy kandydacie do wydania trójki i od tamtej pory nikt go nie przesunął, więc npm install @docusaurus/core@next da Ci starą wersję, a nie przedpremierową czwórkę.

Czwórka istnieje natomiast w innej postaci, i to już w wydanej wersji 3.10.2. W pliku lib/server/configValidation.js opublikowanej paczki znajdują się flagi future.v4 z czterema pozycjami: useCssCascadeLayers, siteStorageNamespacing, fasterByDefault i mdx1CompatDisabledByDefault. Wszystkie mają domyślnie wartość false. To mechanizm przygotowania strony na kolejne wydanie główne bez czekania na nie. Praktyczny wniosek: możesz zaczynać na trójce, ale włącz te flagi od razu, bo później migracja będzie polegała na naprawianiu czterech rzeczy naraz zamiast po kolei.

Rytm wydań trzeba sprawdzić, a nie założyć. Wersje stabilne szły tak: 3.9.2 wyszła 17 października 2025 roku, 3.10.0 dopiero 7 kwietnia 2026, czyli po niemal sześciu miesiącach przerwy, 3.10.1 dwadzieścia trzy dni później, 30 kwietnia 2026, a 3.10.2 dziesiątego lipca 2026. Dziś, 22 sierpnia 2026, mija zatem sześć tygodni od ostatniego wydania i przy tym rozkładzie to mieści się w normie, bo półroczne przerwy już się zdarzały. Gałąź główna żyje: ostatnie zatwierdzenia w kanale main pochodzą z 21 sierpnia 2026, czyli sprzed doby. Osobno rzuca się w oczy, że kanał canary stanął na paczce z 4 czerwca 2026, więc automatyczne publikowanie wersji rozwojowych nie działa tak regularnie, jak wskazywałby ruch w repozytorium.

Start projektu i struktura konfiguracji

Wejście w projekt jest krótkie i nie wymaga globalnych instalacji.

npx create-docusaurus@latest my-website classic --typescript
cd my-website
npm run start
npm run build
npm run serve

Szablon classic zawiera @docusaurus/preset-classic, czyli wtyczkę dokumentacji, wtyczkę bloga, wtyczkę stron oraz motyw z obsługą trybu ciemnego. Flaga --typescript przełącza szablon na wariant z TypeScriptem. Skrypty w wygenerowanym package.json to start, build, swizzle, deploy, clear, serve, write-translations i write-heading-ids, wszystkie są cienkimi opakowaniami na polecenie docusaurus.

Cała konfiguracja mieści się w jednym pliku docusaurus.config.js. Sekcja, o której warto wiedzieć od pierwszego dnia, to future, bo to tam siedzą flagi przyspieszające budowanie i flagi przygotowujące na wersję czwartą.

// docusaurus.config.js
export default {
  future: {
    v4: {
      useCssCascadeLayers: true,
      siteStorageNamespacing: true,
      fasterByDefault: true,
      mdx1CompatDisabledByDefault: true,
    },
    faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      rspackPersistentCache: true,
      mdxCrossCompilerCache: true,
      ssgWorkerThreads: true,
      gitEagerVcs: true,
    },
  },
};

Każda z tych flag ma konkretne znaczenie: swcJsLoader zastępuje Babel przez SWC, lightningCssMinimizer zastępuje cssnano i clean-css, rspackBundler zastępuje webpacka przez Rspack, rspackPersistentCache dokłada trwałą pamięć podręczną i wymaga zachowania katalogu ./node_modules/.cache między budowaniami, ssgWorkerThreads rozkłada generowanie statycznych stron na pulę wątków, a gitEagerVcs czyta całe repozytorium Git na raz zamiast pliku po pliku, co ma znaczenie przy dużych repozytoriach. Sekcja faster wymaga dodania pakietu @docusaurus/faster do zależności. W wydaniu 3.10.2 wszystkie te flagi są domyślnie wyłączone, chyba że włączysz future.v4.fasterByDefault.

Dokumentacja zawiera też ostrzeżenie, które łatwo przeoczyć: funkcje z przedrostkiem experimental_ lub unstable_, na przykład experimental_router i experimental_vcs, mogą się zmienić w wydaniach mniejszych i nie są traktowane jak zmiany łamiące w rozumieniu wersjonowania semantycznego.

Wyszukiwarka, czyli najczęstsza niespodzianka

Docusaurus nie ma wbudowanego wyszukiwania. Oficjalna dokumentacja wymienia cztery drogi i wprost oznacza, która jest wspierana: Algolia DocSearch ma wsparcie pierwszej kategorii od zespołu Docusaurusa, natomiast Typesense DocSearch, wyszukiwanie lokalne oraz własny komponent SearchBar są utrzymywane przez społeczność, z prośbą o zgłaszanie błędów do odpowiednich repozytoriów. To rozróżnienie ma praktyczne skutki, gdy coś przestanie działać po aktualizacji.

Droga oficjalna wygląda tak. Algolia prowadzi darmowy program DocSearch, ale jest on adresowany do publicznej dokumentacji technicznej i technicznych blogów. Strona z kryteriami mówi, że zgłoszenia są zwykle odrzucane, gdy witryna nie jest gotowa produkcyjnie albo zawiera treści nietechniczne. Zgłoszenie składa się przez panel Algolii, gdzie podaje się domenę do weryfikacji względem wymagań programu, a po akceptacji trzeba potwierdzić własność domeny w ciągu siedmiu dni, inaczej crawler przestaje działać. Domyślnie crawler odwiedza stronę raz w tygodniu, a harmonogram da się zmienić w panelu.

Dla dokumentacji produktu komercyjnego oznacza to konkretną rzecz: darmowy program nie jest dla Ciebie i płacisz za Algolię według cennika. Na stronie cennika, w stanie na 22 sierpnia 2026, plan Grow zawiera 10 tysięcy zapytań wyszukiwania miesięcznie, a powyżej tego kosztuje 0,50 dolara za każdy kolejny tysiąc zapytań, oraz 100 tysięcy rekordów, a powyżej 0,40 dolara za kolejny tysiąc rekordów. Plan Grow Plus ma te same progi darmowe, ale stawka za nadmiarowe zapytania wynosi 1,75 dolara za tysiąc. Osobno rozliczany jest crawler: sekcja pytań na tej samej stronie podaje, że Grow i Grow Plus zawierają 10 tysięcy przeszukań miesięcznie, a wiersz w tabeli produktów pokazuje „10 000 miesięcznie, potem 0,80 dolara za kolejny tysiąc”. W tym samym wierszu w surowym kodzie strony widnieje jeszcze wartość „5 000 miesięcznie” w kolumnie, której nazwy plan nie da się odczytać bez wykonania skryptów strony. Dwie różne liczby przy jednej pozycji to powód, żeby przed podpisaniem czegokolwiek sprawdzić limit w panelu, a nie w artykule.

Konfiguracja po stronie Docusaurusa jest krótka i wszystkie pola poniżej istnieją naprawdę.

// docusaurus.config.js
export default {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
      externalUrlRegex: 'external\\.com|domain\\.com',
      replaceSearchResultPathname: {
        from: '/docs/',
        to: '/',
      },
      searchParameters: {},
      searchPagePath: 'search',
      insights: false,
    },
  },
};

Pole apiKey to publiczny klucz wyszukiwania i dokumentacja wprost pisze, że można go bezpiecznie umieścić w repozytorium. contextualSearch jest domyślnie włączone i pilnuje, żeby wyniki dotyczyły bieżącej wersji dokumentacji i bieżącego języka, dzięki czemu przeglądając wersję drugą nie dostajesz duplikatów z wersji pierwszej. Filtry kontekstowe są łączone z tym, co podasz w searchParameters.facetFilters. Jest też nowsze pole askAi, przyjmujące identyfikator asystenta albo obiekt z polami assistantId, indexName, apiKey, appId i suggestedQuestions.

Jeden szczegół wersji warto sprawdzić przed aktualizacją. @docusaurus/theme-search-algolia w wersji 3.10.2 deklaruje zależność @docsearch/react w zakresie ^3.9.0 || ^4.3.2, podczas gdy witryna DocSearch ogłasza już wydanie 5.0.0 jako stabilne. Docusaurus na dziś tej piątki nie obsługuje.

Jeśli dokumentacja stoi za zaporą sieciową albo nie kwalifikuje się do darmowego programu, dokumentacja Docusaurusa odsyła do strony „run your own” w serwisie DocSearch. Trzeba wiedzieć, w co się wchodzi: ta strona jest oznaczona jako wersja przestarzała, dotyczy DocSearch 1.x i 2.x, a jej data ostatniej aktualizacji to 1 grudnia 2021 roku. Opisuje uruchamianie obrazu algolia/docsearch-scraper z Dockera, ze sterownikiem ChromeDriver dla stron wymagających JavaScriptu. To działa, ale nie jest ścieżką pielęgnowaną.

Alternatywa lokalna, którą realnie się dziś stosuje, to pakiet społecznościowy.

// docusaurus.config.js
export default {
  themes: [
    [
      require.resolve('@easyops-cn/docusaurus-search-local'),
      {
        hashed: true,
        language: ['en', 'pl'],
        indexDocs: true,
        indexBlog: true,
        indexPages: false,
        docsRouteBasePath: '/docs',
        highlightSearchTermsOnTargetPage: true,
        explicitSearchResultPath: true,
        fuzzyMatchingDistance: 1,
      },
    ],
  ],
};

@easyops-cn/docusaurus-search-local ma wersję 0.55.3 z 29 lipca 2026 roku i licencję MIT. Indeks powstaje przy budowaniu i jest pobierany przez przeglądarkę, więc rośnie razem z dokumentacją, co przy dużym zbiorze stron oznacza spory plik do ściągnięcia. Opcja hashed dokleja skrót treści, żeby dało się cache'ować indeks długoterminowo. Pułapka konfiguracyjna jest jedna i powtarzalna: w trybie samej dokumentacji, gdy routeBasePath w presetcie ustawisz na /, musisz ustawić docsRouteBasePath na tę samą wartość, inaczej indeks będzie pusty. Starszy pakiet docusaurus-lunr-search ma wersję 3.6.0 opublikowaną 10 stycznia 2025 roku, czyli od ponad półtora roku bez nowego wydania, i nie polecałbym go do nowego projektu.

Wersjonowanie dokumentacji i jego koszt

Wersjonowanie to najmocniejszy argument za Docusaurusem i jednocześnie najdroższa funkcja w tym zestawie. Polecenie docusaurus docs:version 1.1.0 robi trzy rzeczy: kopiuje całą zawartość katalogu docs/ do nowego katalogu versioned_docs/version-1.1.0/, tworzy plik versioned_sidebars/version-1.1.0-sidebars.json na podstawie bieżącej konfiguracji menu bocznego i dopisuje numer wersji do versions.json.

Kopiuje, nie linkuje. Po zamrożeniu trzech wersji masz w repozytorium cztery komplety tych samych plików, a każda poprawka literówki w akapicie obecnym we wszystkich wersjach to cztery osobne edycje albo świadoma decyzja, że starych wersji się nie poprawia.

website
├── docs                         # wersja "current"
│   └── hello.md                 # /docs/next/hello
├── versions.json                # ["1.1.0", "1.0.0"]
├── versioned_docs
│   ├── version-1.1.0
│   │   └── hello.md             # /docs/hello
│   └── version-1.0.0
│       └── hello.md             # /docs/1.0.0/hello
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
└── docusaurus.config.js

Co dokumentacja mówi o czasie budowania, warto zacytować bez upiększeń. Strona o wersjonowaniu zaczyna się od ostrzeżenia, żeby przemyśleć sprawę przed startem, bo wersjonowanie utrudnia współtwórcom pomaganie. Dalej pada zdanie, że w większości przypadków wersjonowanie nie jest potrzebne, ponieważ zwiększy czas budowania i doda złożoności repozytorium, a nadaje się głównie do stron o dużym ruchu i szybkich zmianach dokumentacji między wersjami. Przy opcji onlyIncludeVersions jest wskazówka, żeby w środowisku deweloperskim i w podglądach wdrożeń ograniczyć się do dwóch lub trzech wersji, właśnie po to, żeby skrócić czas startu i budowania.

Czego dokumentacja nie podaje, to liczby. Nie ma tam ani mnożnika, ani wykresu, ani pomiaru pokazującego, o ile procent rośnie czas budowania na wersję. Zależność jest jakościowa: więcej wersji to więcej stron do wygenerowania, więcej plików do przetworzenia i dłuższy przebieg. Jeśli potrzebujesz twardej liczby dla swojego repozytorium, jedyną uczciwą drogą jest zmierzenie budowania z onlyIncludeVersions ustawionym na jedną wersję i porównanie z pełnym zestawem.

Pozostałe opcje wtyczki dokumentacji, które sterują tym zachowaniem, to disableVersioning, includeCurrentVersion, lastVersion oraz słownik versions, w którym dla każdej wersji ustawisz label, path, banner o wartości none, unreleased albo unmaintained, badge oraz className. Jest też chwyt dla projektów, które wydały wersję pierwszą i nie planują drugiej: zamiast zamrażać, ustawiasz lastVersion: 'current' i nadajesz bieżącej wersji label oraz path, dzięki czemu utrzymujesz jeden katalog docs/, a użytkownik widzi numer wersji.

Tłumaczenia i budowanie wielu języków

Tłumaczenia działają na plikach, nie na usłudze zewnętrznej. W konfiguracji deklarujesz i18n.defaultLocale i listę i18n.locales, a potem tłumaczysz trzy rodzaje zasobów. Pliki Markdown i MDX tłumaczy się w całości, bez dzielenia na zdania, żeby zachować kontekst. Etykiety z kodu Reacta i z themeConfig trafiają do plików JSON w formacie Chrome i18n, gdzie każdy klucz ma pola message i description. Trzeci rodzaj to dane wtyczek, na przykład etykiety kategorii w menu bocznym.

npm run write-translations -- --locale fr
npm run start -- --locale fr
npx docusaurus build --locale fr
npx docusaurus build

Polecenie write-translations wykonuje wyłącznie analizę statyczną kodu, nie uruchamia strony, więc komunikaty budowane dynamicznie z wyrażeń nie zostaną wyciągnięte. Polecenie build bez flagi --locale buduje wszystkie znane lokalizacje, a z flagą tylko wskazane, co jest praktyczną furtką, gdy pełne budowanie w potoku ciągłej integracji zaczyna trwać za długo.

Dokumentacja jasno wymienia też, czego system tłumaczeń nie robi: nie wykrywa automatycznie języka użytkownika, bo to zadanie hostingu, nie wspiera żadnego konkretnego dostawcy tłumaczeń jako usługi i nie tłumaczy adresów stron, uznając to za technicznie skomplikowane i mało warte pod kątem wyszukiwarek. Domyślne etykiety motywu klasycznego są już przetłumaczone na wiele języków w pakiecie @docusaurus/theme-translations.

Docusaurus a alternatywy

Kilka pozycji z tej tabeli wymaga komentarza. Starlight ma wyszukiwanie pełnotekstowe oparte na Pagefind włączone domyślnie i bez żadnej konfiguracji, a pojedynczą stronę wyłącza się z indeksu polem pagefind: false w nagłówku pliku. Wersjonowania w rdzeniu nie ma, robi to wtyczka społecznościowa starlight-versions z katalogu wtyczek. Nextra również sięga po Pagefind, co widać w opublikowanej paczce 4.6.1, gdzie komponent wyszukiwania ładuje moduł pagefind/pagefind.js, ale samo wydanie 4.6.1 pochodzi z 4 grudnia 2025 roku, czyli ma już ponad osiem miesięcy. Mintlify opisaliśmy osobno w artykule o Mintlify i tam kluczowa różnica jest inna: repozytorium silnika nie jest publiczne, więc porównanie licencji i wersji nie ma tu odpowiednika.

Kiedy Docusaurus wygrywa. Duży projekt otwarty z kilkoma utrzymywanymi wersjami głównymi, dokumentacją w kilku językach i blogiem wydaniowym dostaje wszystkie trzy funkcje z pudełka, za darmo, bez dostawcy pośrodku. Do tego dochodzi darmowa wyszukiwarka z programu DocSearch, o ile zgłoszenie przejdzie.

Kiedy przegrywa. Przy dokumentacji na trzydzieści stron cała maszyneria jest nadmiarowa i Starlight albo zwykły katalog Markdown w repozytorium wystarczą. Zespół, który nie zna Reacta, przy pierwszej nietypowej zmianie wyglądu utknie na swizzlingu. A jeśli dokumentacja ma być częścią istniejącej aplikacji Next.js, pod jedną domeną i z tym samym stanem zalogowania, to Docusaurus jest osobną aplikacją i osobnym budowaniem, więc Nextra albo własne trasy w Next.js będą prostsze.

Trzy wady wymieńmy wprost, bo żadna nie znika po instalacji. Po pierwsze, całe budowanie to React, więc strona dokumentacji ciągnie za sobą ekosystem Reacta wraz z jego aktualizacjami i konfliktami wersji. Po drugie, migracje między wersjami głównymi wymagały przepisywania konfiguracji, a ślad po tym został w kodzie: opcja markdown.mdx1Compat z domyślnymi comments, admonitions i headingIds istnieje właśnie po to, żeby ułatwić przejście na wersję trzecią, a flaga future.v4.mdx1CompatDisabledByDefault przygotowuje jej wyłączenie. Po trzecie, wyszukiwarka jest zewnętrzną zależnością, a w wariancie oficjalnym także zewnętrzną usługą z własnym cennikiem i własnym regulaminem przyjęć.

Typowe błędy

Zakładanie, że wyszukiwarka po prostu będzie. To najczęstszy błąd i wychodzi na jaw dzień przed wdrożeniem. Decyzję o DocSearch albo o wyszukiwaniu lokalnym trzeba podjąć na starcie, bo zgłoszenie do programu Algolii nie jest natychmiastowe i może zostać odrzucone.

Ukrywanie apiKey w zmiennych środowiskowych. Klucz w konfiguracji algolia to publiczny klucz wyszukiwania i dokumentacja pisze wprost, że można go zatwierdzić w repozytorium. Budowanie wokół niego procedury dla sekretów to strata czasu, a przy okazji utrudnia podglądy wdrożeń.

Wersjonowanie od pierwszego dnia. Zamrożenie wersji, zanim dokumentacja się ustabilizuje, daje dwa katalogi do utrzymania i zero korzyści. Dokumentacja radzi odwrotnie, a chwyt z lastVersion: 'current' pozwala pokazać numer wersji bez kopiowania plików.

Włączenie flag future.faster bez pakietu. Sekcja faster wymaga @docusaurus/faster w zależnościach, podobnie jak future.v4.fasterByDefault. Bez tego pakietu budowanie się nie powiedzie.

Rozjazd docsRouteBasePath przy wyszukiwaniu lokalnym. W trybie samej dokumentacji, gdy routeBasePath presetu jest ustawiony na /, ta sama wartość musi trafić do opcji wtyczki wyszukiwania. Objaw jest mylący, bo strona się buduje, a wyszukiwarka po prostu nic nie znajduje.

Aktualizacja initialIndexSettings w konfiguracji crawlera. Te ustawienia inicjalizują indeks tylko wtedy, gdy jeszcze nie istnieje. Po zmianie zalecane jest usunięcie indeksu i uruchomienie przeszukania od nowa, a nie liczenie na to, że nowa konfiguracja zadziała sama.

FAQ

Czy jest już Docusaurus 4?

Nie w rejestrze npm. Na 22 sierpnia 2026 nie ma tam żadnej paczki @docusaurus/core w wersji 4.x, w żadnym kanale. Znacznik next wskazuje na 3.0.0-rc.1, czyli na kandydata do wydania trójki, więc instalacja z tego kanału cofnie Cię do starszej wersji. Czwórka jest przygotowywana przez flagi future.v4 dostępne już w 3.10.2 i to jest właściwy sposób, żeby się na nią przygotować.

Ile realnie kosztuje wyszukiwarka w projekcie komercyjnym?

Darmowy program DocSearch obejmuje publiczną dokumentację techniczną i techniczne blogi, więc dokumentacja produktu komercyjnego z niego nie skorzysta. Płacisz według cennika Algolii: plan Grow to 10 tysięcy zapytań miesięcznie w cenie planu i 0,50 dolara za każdy kolejny tysiąc, plus 100 tysięcy rekordów i 0,40 dolara za kolejny tysiąc. Grow Plus ma te same progi, ale 1,75 dolara za tysiąc nadmiarowych zapytań. Do tego dochodzi rozliczenie crawlera, przy którym cennik pokazuje dwie różne liczby, więc limit sprawdź w panelu.

Czy da się użyć Docusaurusa bez znajomości Reacta w zespole?

Do pisania i publikowania dokumentacji tak, bo treść to pliki Markdown i MDX, a motyw klasyczny działa bez pisania komponentów. Granica przebiega tam, gdzie kończą się zmienne CSS. Własna strona główna, nietypowy układ strony dokumentu albo zmiana zachowania menu bocznego oznaczają swizzling komponentu motywu, czyli pracę w Reakcie i utrzymywanie tej kopii przy kolejnych aktualizacjach.

Czy wersjonowanie da się wyłączyć po fakcie?

Tak. Opcja disableVersioning wyłącza wersjonowanie mimo obecnych wersji i strona zawiera wtedy tylko wersję bieżącą. Wersję można też usunąć na stałe: skreślasz jej numer z versions.json, kasujesz katalog versioned_docs/version-X i plik versioned_sidebars/version-X-sidebars.json. Jeśli chodzi tylko o skrócenie budowania w podglądach, wystarczy onlyIncludeVersions z dwiema lub trzema wersjami.

Czy Docusaurus nadaje się na dokumentację wewnątrz aplikacji Next.js?

Nie w sensie osadzenia. Docusaurus jest samodzielną aplikacją z własnym budowaniem i własnym routerem, a nie zestawem komponentów do wpięcia w istniejące trasy. Da się go wystawić pod ścieżką /docs na poziomie serwera pośredniczącego, ale to nadal dwa osobne wdrożenia. Gdy dokumentacja ma dzielić układ i sesję z aplikacją, Nextra albo własne strony MDX w projekcie Next.js są bliżej celu.

Co dają flagi Docusaurus Faster i czy warto je włączyć?

Podmieniają wolniejsze narzędzia na szybsze: SWC zamiast Babel przy transpilacji i minifikacji, Lightning CSS zamiast cssnano i clean-css, Rspack zamiast webpacka, pula wątków przy generowaniu stron statycznych i szybszy odczyt danych z Gita. W 3.10.2 są domyślnie wyłączone, wymagają pakietu @docusaurus/faster, a rspackPersistentCache dodatkowo wymaga zachowania katalogu ./node_modules/.cache między budowaniami. Włączać warto, ale pomiar zrób na własnym repozytorium, bo zysk zależy od liczby stron i wersji.