Zarządzanie bazą wiedzy

Ten dokument tłumaczy, kto i jak zmienia treść strony docs.atlantestates.com. Skierowany do Igora, Anny i każdej osoby, która ma uprawnienia do edycji.

Jak działa baza pod spodem

Strona, którą czytasz, to statyczna strona internetowa zbudowana z plików Markdown (MDX). Cała treść siedzi w katalogu content/ w repozytorium Git:


docs-site/
└── content/
    ├── company/          ← O firmie
    ├── onboarding/       ← Kurs wdrożeniowy (M01-M13)
    ├── tools/            ← Narzędzia (Bitrix24, AtlantCRM, …)
    ├── reference/        ← Materiały (Słownik, Skrypty, Szablony, FAQ)
    ├── zarzadzanie/      ← Ten plik
    └── tests/            ← Testy

Każdy plik .mdx to jedna strona. Każdy katalog ma plik _meta.ts, który ustala kolejność i tytuły w sidebar.

Workflow zmiany:

Edytujesz plik MDX (lokalnie lub przez interfejs GitHuba).
Commit + push do gałęzi main.
Vercel automatycznie buduje i deployuje nową wersję na docs.atlantestates.com (~30–60 s).

Jak edytować istniejącą stronę

Wariant A — Edytor CMS w przeglądarce ⭐ (najprostszy)

Adres: docs.atlantestates.com/admin/

Wizualny edytor (Decap CMS) prowadzi Cię przez treść bez znajomości Markdowna. Zmiany są zapisywane bezpośrednio jako commit do GitHuba.

Otwórz /admin/.
Zaloguj się przez konto GitHub (autoryzacja jednorazowa).
Wybierz sekcję (O firmie / Kurs wdrożeniowy / Narzędzia / …).
Kliknij stronę do edycji.
Popraw treść w edytorze (tekst, pogrubienie, listy, obrazki, linki).
Kliknij Save (draft) lub Publish (od razu na produkcję).
Po ~1 minucie zmiana będzie na docs.atlantestates.com.

Wymaganie: Twoje konto GitHub musi mieć uprawnienia do repozytorium atlant-estates/docs. Prosisz Igora o dodanie.

Wariant B — przez interfejs GitHuba (edycja pliku bezpośrednio)

Na każdej stronie na dole jest link „Edytuj tę stronę na GitHubie →”. Kliknij go.
Klikasz ikonkę ołówka (Edit this file) — trafiasz w edytor GitHuba.
Edytujesz treść MDX w przeglądarce.
Na dole: napisz krótki commit message (np. „Aktualizacja adresu KRS”) i kliknij Commit changes.
Po ~1 minucie zmiana będzie na docs.atlantestates.com.

Wariant C — lokalnie z `git` (dla bardziej złożonych zmian)


git clone git@github.com:atlant-estates/docs.git
cd docs/docs-site
npm install
npm run dev   # podgląd na localhost:3000
# … edytujesz pliki …
git add content/<plik>.mdx
git commit -m "Opis zmiany"
git push

Jak dodać nową stronę

Przykład: chcesz dodać moduł M14 do kursu wdrożeniowego.

1. Utwórz nowy plik MDX

W katalogu content/onboarding/ stwórz m14.mdx:


---
title: M14 — Nazwa nowego modułu
description: Krótki opis modułu (do SEO i meta-tagów)
---
 
# M14 — Nazwa nowego modułu
 
Treść modułu w Markdown.
 
## Sekcja H2
 
- punkt
- punkt
 
## Test
 
(TODO)

2. Dodaj do `_meta.ts`

Edytuj content/onboarding/_meta.ts, dopisz nowy klucz w odpowiednim miejscu (kolejność = kolejność w sidebar):


export default {
  // … istniejące …
  m13: 'M13 — Podstawy prawne',
  m14: 'M14 — Nazwa nowego modułu'   // ← dopisane
}

3. Push


git add content/onboarding/m14.mdx content/onboarding/_meta.ts
git commit -m "Dodaj moduł M14"
git push

Jak usunąć stronę

Usuń plik MDX (git rm content/onboarding/m14.mdx).
Usuń wpis z _meta.ts dla tego pliku — inaczej build padnie.
Sprawdź, czy żaden inny plik nie linkuje do tej strony (grep -rn "/onboarding/m14" content/). Jeśli tak — popraw lub usuń linki.
Commit + push.

Jak dodać obrazek / zrzut ekranu

Wrzuć plik (jpg/png) do docs-site/public/<podkatalog>/. Przykład: public/notion/bitrix24/screen.jpg.
W MDX odwołaj się ścieżką absolutną (zaczyna się od /):


![Opis obrazka dla SEO/a11y](/notion/bitrix24/screen.jpg)

Push.

Zasady:

Maksymalny rozmiar obrazka: ~500 KB. Większe — kompresuj (np. tinypng.com ).
Nazwa pliku — bez polskich znaków i spacji.
Każdy ![…]() musi mieć opis (alt text) — pierwsza rzecz dla SEO i dostępności.

Struktura katalogów — gdzie co siedzi

Katalog	Co tam wkładać
`content/company/`	Fakty o firmie, zespół, historia
`content/onboarding/m01..m13.mdx`	Moduły kursu — jeden plik na moduł
`content/tools/<narzedzie>/`	Instrukcja konkretnego narzędzia (Bitrix24, AtlantCRM, Zadarma, properly, nBot…)
`content/reference/glossary.mdx`	Słownik pojęć
`content/reference/scripts/`	Skrypty rozmów (po polsku)
`content/reference/templates/`	Szablony dokumentów (umowy, listy, marketing)
`content/reference/prawo/`	Pełna sekcja prawna (umowy, RODO, AML, etyka)
`content/reference/faq/`	Często zadawane pytania wewnętrzne
`content/zarzadzanie/`	Ta strona
`public/notion/<sekcja>/`	Obrazki / zrzuty importowane z Notion

Reguły pisania treści

Po polsku. Cała baza jest po polsku — to jest język agenta w Polsce.
Krótko i konkretnie. To nie jest blog — to instrukcja do pracy.
Nie wymyślaj. Jeśli nie znasz odpowiedzi — napisz TODO i przekaż osobie, która wie.
Polskich terminów prawnych nie tłumacz. umowa najmu, akt notarialny, ryczałt, KRS, NIP — zostają jak są.
Liczby i daty — dokładnie. Nie zaokrąglaj („800 000 zł” — nie „800K”). Daty z określoną dokładnością („do 30 kwietnia” — nie „pod koniec kwietnia”).
Frontmatter description — krótkie zdanie (do 150 znaków). Jeśli zawiera dwukropek : — wrap w cudzysłowach: description: "Coś: cośtam".
Bez < przed cyfrą — w MDX <1 jest interpretowane jako początek tagu JSX. Zamiast tego pisz mniej niż 1 lub < 1 (ze spacją).

Co NIE może trafić do bazy

Dane osobowe pracowników (prywatne sprawy, warunki współpracy, powody zwolnień). Wszystko, co dotyczy osób — tylko ogólne role.
Hasła, klucze API, tokeny. Nigdy w plikach MDX. Idą do zmiennych środowiskowych (.env.local — nieshareowane).
Dane prywatne klientów (telefony, emaile, PESEL). Przykłady muszą być anonimowe.
Treści Costa del Sol i Franczyzy. Te obszary są poza zakresem tej bazy (osobne projekty).

Deploy i kontrola wersji

Każdy commit do main automatycznie deployuje się na docs.atlantestates.com.
Pull request (jeśli wprowadzasz większą zmianę) — Vercel buduje preview pod tymczasowym URL-em. Można obejrzeć przed merge’em.
Rollback: każdy stary commit jest gotowy do przywrócenia jednym kliknięciem w Vercel dashboard (Deployments → Promote to production).
Historia: wszystko jest w git — kto zmienił, kiedy, dlaczego (commit message).

Kogo pytać o pomoc

Treść (co napisać) → Igor
Forma (jak napisać, struktura) → Igor / Anna
Problem techniczny (build pada, obrazek się nie wyświetla, link nie działa) → Igor
Vercel / DNS / Cloudflare Access → Igor

Roadmap (co planujemy dodać)

Asystent AI w AtlantCRM — odpytuje tę bazę (RAG)
Pytania testowe per moduł (M01–M13)
Pełen import szablonów umów z katalogu !UMOWY
Dane analityczne — które strony są czytane, jakie pytania zadają agenci
Tryb dwujęzyczny (PL + EN) dla agentów anglojęzycznych