Jak przestać konfigurować wiki i zacząć pisać dokumentację

Znana historia: twój zespół lub ty osobiście potrzebujecie bazy wiedzy. Otwierasz Wiki.js, Outline lub, broń Boże, Confluence. Godzinę później orientujesz się, że głęboko konfigurujesz PostgreSQL, Redis, magazyn S3 i trzystuwierszowy plik Docker Compose. W tym momencie chęć spisania kilku mądrych myśli zwykle znika.

Ostatnio natknąłem się na LeafWiki. Autor projektu najwyraźniej podziela ten ból. To prosta samohostowana wiki działająca na zasadzie „pobierz i uruchom”. Bez ciężkich zależności, tylko jeden plik binarny Go i folder z danymi.

Pod maską

LeafWiki nie próbuje na nowo wynajdywać koła. Opiera się na trzech prostych rzeczach: Go dla backendu, React dla interfejsu i SQLite dla metadanych. Najlepsze jest to, że rzeczywista zawartość stron jest przechowywana w zwykłych plikach Markdown na dysku.

To oznacza, że jeśli serwer nagle się zawali lub zdecydujesz się przenieść do innego narzędzia, twoje dane nie zamienią się w dynię uwięzioną w zastrzeżonej bazie danych. Możesz otworzyć je dowolnym edytorem tekstu lub nawet Obsidian.

Co sprawia, że jest dobra w praktyce

Często widzę narzędzia, które nazywają siebie „prostymi", ale w rzeczywistości wymagają pełnej administracji. LeafWiki jest w tej kwestii bardziej uczciwa.

Struktura drzewa zamiast chaosu

Wiele nowoczesnych narzędzi do robienia notatek skłania się ku „płaskim" listom z tagami. Tutaj otrzymujesz klasyczną strukturę drzewa. Sam definiujesz hierarchię, a co ważne, możesz ręcznie sortować strony w sekcjach. Jest to kluczowe dla dokumentów wdrożeniowych lub proceduralnych, gdzie kolejność czytania ma znaczenie.

Edytor, który nie przeszkadza

Zawiera wbudowany edytor Markdown z podglądem na żywo. Obsługuje tabele, listy zadań, przypisy, a nawet diagramy Mermaid z formułami matematycznymi KaTeX. Jest autouzupełnianie linków wewnętrznych — zacznij wpisywać nazwę innej strony, a wiki automatycznie wstawi poprawny link.

Inteligentne linki

System śledzi linki zwrotne. Na każdej stronie możesz zobaczyć, co do niej odsyła. Jeśli zmienisz nazwę lub przeniesiesz stronę, LeafWiki może automatycznie zaktualizować linki w innych dokumentach (ta funkcja wymaga włączenia flagi --enable-link-refactor).

Kopia zapasowa dla paranoików

Oprócz prostego kopiowania folderu danych, najnowsze wersje dodały eksperymentalną obsługę kopii zapasowych Git. Wiki będzie automatycznie pushować zmiany do twojego zdalnego repozytorium zgodnie z harmonogramem.

Dla kogo to nie jest

Powiedzmy to jasno na wstępie: to nie jest zamiennik Notion. Nie ma prawdziwej współpracy w czasie rzeczywistym, gdzie widzisz kursory kolegów. Nie ma też skomplikowanych procesów zatwierdzania publikacji. Jeśli potrzebujesz, żeby dziesięć osób jednocześnie edytowało ten sam akapit — szukaj dalej.

Ponadto LeafWiki nie obsługuje jeszcze szczegółowej kontroli dostępu na poziomie poszczególnych gałęzi drzewa. Role istnieją (admin, edytor, czytelnik), ale mają zastosowanie do całej wiki.

Jak zacząć

Jeśli masz zainstalowanego Dockera, uruchomienie zajmuje około trzydziestu sekund.

docker run -p 8080:8080 \
    -v ~/leafwiki-data:/app/data \
    ghcr.io/perber/leafwiki:latest \
    --jwt-secret=super-secret-key \
    --admin-password=your-password \
    --allow-insecure=true

Flagi --allow-insecure=true potrzebujesz, jeśli uruchamiasz projekt lokalnie bez HTTPS. Jeśli planujesz wystawiać go zewnętrznie przez Nginx lub inny serwer proxy, lepiej usuń tę flagę.

Przy okazji, dla entuzjastów minimalizmu, istnieje gotowy instalator dla Linuksa, który rejestruje LeafWiki jako usługę systemową:

sudo /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/perber/leafwiki/main/install.sh)"

Praca z urządzeniami mobilnymi

Interfejs jest responsywny. Edycja tekstu z telefonu to wątpliwa przyjemność, ale czytanie dokumentacji w podróży lub szybkie poprawienie literówki jest całkowicie wykonalne.

LeafWiki zdobywa cię swoją przewidywalnością. Świetnie sprawdza się przy:

• Osobistym dzienniku technicznym lub bazie wiedzy.
• Dokumentacji dla małego projektu.
• Wewnętrznych instrukcjach dla administratorów lub inżynierów DevOps.

Jeśli masz dość walki z ciężkimi silnikami wiki i po prostu chcesz pisać Markdown, który zostanie schludnie uporządkowany — wypróbuj ten projekt. Obecnie ma nieco poniżej tysiąca gwiazdek na GitHubie, ale zdecydowanie ma potencjał, by stać się „tym prostym narzędziem", którego szukałeś.