Eksport i utrzymanie dokumentu

Struktura projektu

• mkdocs.yml — pełna strona i nawigacja;
• mkdocs-pdf.yml — opcjonalny eksport do jednego PDF przez utrzymywany plugin mkdocs-to-pdf;
• docs/ — źródła Markdown, Mermaid, CSS i JavaScript;
• requirements.txt — zależności strony;
• requirements-pdf.txt — dodatkowy eksporter PDF;
• site/ — generowany wynik, ignorowany i nieedytowany ręcznie;
• scripts/validate_site.py — walidacja struktury, nawigacji i linków.

Lokalny podgląd

Serwer NORBI nie jest potrzebny i powinien pozostać wyłączony. Podgląd MkDocs jest oddzielnym, lokalnym serwerem dokumentacji. W izolowanym środowisku projektu należy zainstalować zależności z requirements.txt, a następnie uruchomić mkdocs serve. Strona jest dostępna wyłącznie lokalnie, dopóki użytkownik nie skonfiguruje innego bindingu lub hostingu.

Build statyczny

mkdocs build --strict generuje katalog site/. Tryb strict traktuje ostrzeżenia nawigacji i linków jako błąd. Wynik można skopiować do prywatnego serwera statycznego dopiero po osobnej decyzji o publikacji i security review. Nie należy publikować source artifacts, sekretów ani danych klienta razem ze stroną.

PDF

Eksport wymaga dodatkowych zależności z requirements-pdf.txt. Konfiguracja mkdocs-pdf.yml generuje norbi-product-vision.pdf po ustawieniu flagi środowiskowej ENABLE_PDF_EXPORT. Przed przekazaniem PDF należy wyrenderować wszystkie strony i sprawdzić: spis treści, podziały stron, tabele, diagramy, polskie znaki, linki i samotne nagłówki. Eksport HTML przez drukarkę systemową jest fallbackiem, ale może inaczej łamać Mermaid i tabele.

Mermaid i praca offline

Diagramy są obsługiwane natywnie przez Material for MkDocs na podstawie bloków mermaid. Po zbudowaniu statycznym nie wymagają połączenia z usługą AI. Należy zachować wersję Material w lock/requirements po zaakceptowaniu środowiska. Zmiana renderer version może zmienić layout diagramu i wymaga visual QA.

Aktualizacja treści

1. Zmień właściwy rozdział, nie twórz równoległej kopii „v2”.
2. Zaktualizuj odnośniki, diagramy i rejestr kontraktów, jeśli zmienia się semantyka.
3. Uruchom walidator projektu.
4. Zbuduj stronę w trybie strict.
5. Przejrzyj zmienione strony na desktopie i telefonie.
6. Przy dużej zmianie wygeneruj PDF i wykonaj render/QA.
7. Publikacja, commit, tag i hosting są osobnymi decyzjami.

Kryteria dokumentu

Dokument nie opisuje bieżącego stanu developmentu. Funkcje są target contracts. Gdy decyzja jest niezamknięta, treść pokazuje warianty i kryterium decyzji zamiast wymyślać fakt. Każdy większy moduł ma kartę: cel, odpowiedzialności, wejścia, wyjścia, zależności, kontrakty, uprawnienia, autonomia, polecenia, przebieg, walidacja, błędy, ryzyka i awaria.

Kontrola jakości

Automatyczna walidacja sprawdza:

• czy każdy plik z nawigacji istnieje i nie jest powtórzony;
• czy wszystkie Markdown są w nav;
• czy lokalne linki wskazują istniejące pliki;
• czy Mermaid fences są domknięte;
• czy pliki mają tytuł H1, UTF-8 bez BOM i NUL;
• liczbę słów, plików, nagłówków i diagramów;
• czy nie ma sygnałów niedokończonej lub zastępczej treści.

Automaty nie oceniają poprawności biznesowej, kompletności prawnej ani czytelności wizualnej. Te obszary wymagają przeglądu człowieka oraz docelowo konsultantów domenowych.