Przejdź do głównej zawartości

Wdrażanie strony dokumentacji

Dokumentacja CakeMarket (Docusaurus) jest dołączona do głównej aplikacji Next.js i serwowana pod /docs na tym samym Cloudflare Worker. Nie ma osobnego wdrożenia — dokumentacja jest budowana jako pliki statyczne i kopiowana do public/docs/ przed budowaniem Next.js.

Jak to działa​

  1. npm run build:docs buduje stronę Docusaurus z baseUrl: /docs/
  2. Zbudowane pliki są kopiowane z docs/build/ do public/docs/
  3. Next.js pobiera public/docs/ jako zasoby statyczne
  4. Build OpenNext/Cloudflare pakuje je do .open-next/assets
  5. Worker cakemarketdev serwuje wszystko — aplikację i dokumentację — z jednego wdrożenia

Polecenia budowania​

PolecenieOpis
npm run build:docsBuduj tylko dokumentację (do public/docs/)
npm run buildBuduj dokumentację + aplikację Next.js
npm run deployBuduj dokumentację + Next.js + wdróż na Cloudflare
npm run previewBuduj dokumentację + Next.js + lokalny podgląd

Lokalne rozwijanie​

Aby pracować nad dokumentacją lokalnie:

cd docs
npm install
npm start

Uruchamia to serwer deweloperski Docusaurus pod adresem http://localhost:3000/docs/.

Konfiguracja​

Kluczowe pliki:

docs/
├── docusaurus.config.ts    # baseUrl: /docs/, url: cakemarket.app
├── sidebars.ts             # Struktura nawigacji bocznej
├── docs/                   # Treść Markdown
│   ├── user-guides/        # Przewodniki dla kupujących, sprzedających, administratorów
│   ├── tech/               # Dokumentacja techniczna
│   └── legal/              # Dokumenty prawne
├── src/css/custom.css      # Niestandardowe style
├── static/                 # Zasoby statyczne (obrazy, ikony)
└── package.json            # Zależności

Katalog public/docs/ jest w gitignore — jest generowany podczas budowania.

Aktualizacja dokumentacji​

  1. Edytuj pliki Markdown w docs/docs/
  2. Testuj lokalnie: cd docs && npm start
  3. Zatwierdź i wypchnij — następne wdrożenie będzie zawierać zaktualizowaną dokumentację

Rozwiązywanie problemów​

Budowanie kończy się błędem uszkodzonych linków​

Docusaurus jest skonfigurowany z onBrokenLinks: 'throw'. Napraw wszystkie uszkodzone linki wewnętrzne przed wypchnięciem. Uruchom cd docs && npm run build lokalnie, aby sprawdzić.

Zasoby statyczne się nie ładują​

Upewnij się, że pliki statyczne znajdują się w docs/static/ i są odwoływane ze ścieżkami względnymi do bazowego URL dokumentacji (np. /docs/img/screenshot.png w produkcji).