4

Rozdział 4 z 11

Dokumentacja projektów w vaultcie

Opublikowany

Przenosimy dokumentację projektów do vaulta tak, żeby repozytorium pozostało źródłem prawdy, a kopię dało się odświeżyć jedną komendą. Każdy projekt dostaje notatkę główną na Twoje uwagi.

Czego się nauczysz

  • Kopia czy przeniesienie — źródło prawdy
  • Struktura folderu projektu
  • Skrypt synchronizacji (bash)
  • Notatka główna projektu, callouty i linki ze ścieżką

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 -rf usuwa tylko folder Technical-docs w 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ów README.md i 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.sh działa i kopiuje README oraz docs/.
  • 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.

Narzędzia / paczki

bash sed Obsidian callouts

Spis treści