Rozdział 4: Dokumentacja projektów w vaultcie
Dokumentacja Twoich projektów (README, folder docs/) leży w repozytoriach kodu. W tym rozdziale przenosimy ją do vaulta, żeby była w jednym miejscu z resztą wiedzy i żeby agent AI mógł ją czytać. Robimy to tak, żeby jedna wersja była zawsze źródłem prawdy, a kopię dało się odświeżyć jedną komendą.
Po tym rozdziale każdy projekt ma w
01-Projects/swój folder z kopią dokumentacji i notatkę główną, a skrypt odświeża kopię w kilka sekund.
Kopia czy przeniesienie?
Dokumentacja musi zostać w repozytorium projektu: tam ją edytujesz razem z kodem, tam widzi ją zespół, z niej buduje się strona. Do vaulta trafia kopia.
To rodzi jedno pytanie: co, jeśli zmienisz docs w repo? Kopia się zestarzeje. Dlatego ustalamy prostą zasadę:
| Plik | Gdzie edytujesz | Jak trafia do vaulta |
|---|---|---|
README, docs/ |
w repozytorium projektu | skryptem synchronizacji |
notatka główna projektu (<projekt>.md) |
w Obsidianie | piszesz ją sam; skrypt jej nie rusza |
Zasada: kopii w vaultcie nie edytujesz. Skrypt nadpisuje ją przy każdym odświeżeniu, więc zmiany by przepadły. Własne uwagi piszesz w notatce głównej.
Struktura folderu projektu
Przykład dla projektu moj-projekt:
01-Projects/moj-projekt/
├── moj-projekt.md # notatka główna (Twoja)
├── README.md # kopia z repo
└── Technical-docs/ # kopia folderu docs/ z repo
Gdy projekt ma większą dokumentację, dziel ją tak, jak dzieli się w repo. U nas strona z kursami ma podfolder Site-projects/ z osobnym folderem na każdy kurs (Blog, CI/CD, Hermes…) i spisem rozdziałów w każdym.
Krok 1 — Skrypt synchronizacji 💻
Skrypty trzymamy w vaultcie, w folderze _scripts/. Obsidian nie pokazuje plików .sh, więc nie zaśmiecają widoku.
Utwórz plik _scripts/sync-moj-projekt.sh:
#!/usr/bin/env bash
# Kopiuje README i docs/ z repo projektu do vaulta Obsidian.
# Pliki w folderze docelowym są KOPIĄ – edytuj je w repo, potem uruchom skrypt ponownie.
set -euo pipefail
SRC="${1:-$HOME/Projekty/moj-projekt}"
VAULT="$(cd "$(dirname "$0")/.." && pwd)"
DST="$VAULT/01-Projects/moj-projekt"
mkdir -p "$DST"
# README – linki docs/... prowadzą teraz do Technical-docs/...
sed -e 's#](docs/#](Technical-docs/#g' "$SRC/README.md" > "$DST/README.md"
# docs/ – zawsze świeża kopia
if [ -d "$SRC/docs" ]; then
rm -rf "$DST/Technical-docs"
cp -R "$SRC/docs" "$DST/Technical-docs"
fi
echo "Zsynchronizowano: $SRC -> $DST"
Co tu się dzieje:
| Fragment | Działanie |
|---|---|
SRC=... |
ścieżka do repo projektu (można podać inną jako argument) |
VAULT=... |
vault wyliczany z położenia skryptu, więc działa z każdego miejsca |
sed ... |
poprawia linki w README, żeby w Obsidianie prowadziły do właściwych plików |
rm -rf + cp -R |
usuwa starą kopię docs i wstawia świeżą (usunięte w repo pliki znikną też z vaulta) |
rm -rfusuwa tylko folderTechnical-docsw vaultcie, czyli kopię. Twoja notatka główna leży obok i jest bezpieczna.
Nadaj prawo uruchamiania i odpal:
chmod +x _scripts/sync-moj-projekt.sh
./_scripts/sync-moj-projekt.sh
Oczekiwany rezultat: komunikat Zsynchronizowano: …, a w Obsidianie pojawia się folder projektu z README i dokumentacją.
Krok 2 — Notatka główna projektu 📱
W 01-Projects/moj-projekt/ utwórz moj-projekt.md. Możesz użyć szablonu Projekt z Rozdziału 3. Przykład:
---
tags: [projekt]
repo: https://github.com/TWOJ_LOGIN/moj-projekt
lokalnie: ~/Projekty/moj-projekt
status: aktywny
---
# moj-projekt
Jedno-dwa zdania: co to za projekt i na czym stoi.
> [!info] Kopia dokumentacji z repo
> README i Technical-docs to kopia z repo. Edytuj w repo,
> potem odśwież skryptem `_scripts/sync-moj-projekt.sh`.
> Ta notatka nie jest nadpisywana, więc tu piszesz własne uwagi.
## Dokumentacja
- [[01-Projects/moj-projekt/README.md|README]]: instalacja, komendy, stack
## Szybki start
| Komenda | Co robi |
|---|---|
| `make start` | uruchamia projekt |
## Moje notatki
Kilka elementów, które tu pierwszy raz widzisz:
> [!info]to callout, czyli kolorowa ramka w Obsidianie (są też[!warning],[!tip]…).[[01-Projects/moj-projekt/README.md|README]]to link z pełną ścieżką. Używamy jej, bo w vaultcie będzie wiele plikówREADME.mdi sama nazwa byłaby niejednoznaczna.- Sekcja „Szybki start” to Twój skrót najważniejszych komend; nie musisz otwierać README za każdym razem.
Wskazówka: w notatce głównej zapisuj rzeczy, których nie ma w README, a są ważne. U nas była to np. informacja z
Makefile, że dwie wtyczki WordPressa są celowo wyłączone lokalnie i działają tylko na produkcji.
Krok 3 — Kolejne projekty
Dla każdego projektu powtórz kroki 1–2: skopiuj skrypt, zmień nazwę projektu i ścieżkę, utwórz notatkę główną. Jeśli w repo nie ma folderu docs/, skrypt skopiuje samo README. Gdy docs/ kiedyś się pojawi, zostanie skopiowany automatycznie.
Na koniec dodaj projekty do Start.md:
## Projekty
- [[01-Projects/moj-projekt/moj-projekt.md|moj-projekt]]
Kiedy odświeżać kopię
Po każdej większej zmianie dokumentacji w repo uruchom skrypt danego projektu:
~/Projekty/moja-baza/_scripts/sync-moj-projekt.sh
W Rozdziale 6 zobaczysz, że po odświeżeniu warto poprosić agenta AI, żeby przetworzył nową dokumentację do wiki. A w Rozdziale 11 zautomatyzujemy samo odświeżanie: GitHub zrobi to za Ciebie po każdej zmianie dokumentacji.
Weryfikacja rozdziału
- Skrypt
_scripts/sync-moj-projekt.shdziała i kopiuje README orazdocs/. - Linki z README do dokumentacji działają w Obsidianie.
- Notatka główna projektu istnieje i ma callout o kopii.
- Ponowne uruchomienie skryptu nie zmienia notatki głównej.
Podsumowanie
- ✅ Rozumiesz zasadę: repo jest źródłem prawdy, vault ma kopię.
- ✅ Masz skrypt, który odświeża kopię jedną komendą.
- ✅ Każdy projekt ma notatkę główną na Twoje własne uwagi.
- ✅ Znasz callouty i linki z pełną ścieżką.
Po tym rozdziale vault zawiera Twoją dokumentację. W następnym rozdziale najważniejsza część: zamieniamy vault w „drugi mózg” prowadzony przez AI, czyli piszemy schemat LLM Wiki.
Dalej: Rozdział 5 — Schemat LLM Wiki: CLAUDE.md, index.md, log.md.