Come smettere di configurare wiki e iniziare a scrivere documentazione

Una storia familiare: il tuo team o tu stesso avete bisogno di una knowledge base. Apri Wiki.js, Outline, o, Dio non voglia, Confluence. Un'ora dopo ti ritrovi a configurare PostgreSQL, Redis, S3 storage e un file Docker Compose di trecento righe. A questo punto, la voglia di annotare due pensieri intelligenti di solito svanisce.

Recentemente ho scoperto LeafWiki. L'autore del progetto condivide chiaramente questo dolore. È un wiki self-hosted essenziale che funziona sul principio "scarica ed esegui". Nessuna dipendenza pesante, solo un singolo binario Go e una cartella dati.

Sotto il cofano

LeafWiki non cerca di reinventare la ruota. Si basa su tre cose semplici: Go per il backend, React per l'interfaccia e SQLite per i metadati. La parte migliore — il contenuto effettivo delle pagine è memorizzato in semplici file Markdown su disco.

Questo significa che se il server dovesse crashare improvvisamente o decidessi di passare a un altro strumento, i tuoi dati non si trasformeranno in una zucca intrappolata in un database proprietario. Puoi aprirlo con qualsiasi editor di testo o persino Obsidian.

Cosa la rende efficace nella pratica

Spesso vedo strumenti che si definiscono "semplici" ma in realtà richiedono un'amministrazione completa. LeafWiki è più onesta a riguardo.

Struttura ad albero invece del caos

Molti strumenti moderni per prendere appunti tendono verso liste "piatte" con tag. Qui ottieni una classica struttura ad albero. Definisci tu stesso la gerarchia e, cosa importante, puoi ordinare manualmente le pagine all'interno delle sezioni. Questo è fondamentale per documenti di onboarding o procedurali dove l'ordine di lettura conta.

Un editor che non dà fastidio

Include un editor Markdown integrato con anteprima in tempo reale. Supporta tabelle, liste di attività, note a piè di pagina e persino diagrammi Mermaid con formule matematiche KaTeX. C'è l'auto-completamento per i link interni — inizia a digitare il nome di un'altra pagina e il wiki inserisce automaticamente il link corretto.

Link intelligenti

Il sistema traccia i backlink. In ogni pagina puoi vedere cosa la referenzia. Se rinomini o sposti una pagina, LeafWiki può aggiornare automaticamente i link negli altri documenti (questa funzione deve essere abilitata con un flag --enable-link-refactor).

Backup per i paranoici

Oltre a copiare semplicemente la cartella dati, le versioni recenti hanno aggiunto il supporto sperimentale per il backup Git. Il wiki pusha automaticamente le modifiche al tuo repository remoto su una pianificazione.

Per chi non è

Sii chiaro fin dall'inizio: non è un sostituto di Notion. Non c'è editing collaborativo in tempo reale dove vedi i cursori dei colleghi. Nessun workflow complesso di approvazione per la pubblicazione. Se hai bisogno che dieci persone modifichino lo stesso paragrafo contemporaneamente — continua a cercare.

Inoltre, LeafWiki non supporta ancora il controllo degli accessi granulare fino ai singoli rami dell'albero. I ruoli esistono (admin, editor, reader), ma si applicano all'intero wiki.

Come iniziare

Se hai Docker installato, lanciarlo richiede circa trenta secondi.

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

Il flag --allow-insecure=true è necessario se stai eseguendo il progetto localmente senza HTTPS. Se pensi di esporlo esternamente tramite Nginx o un altro proxy, è meglio rimuovere questo flag.

A proposito, per gli appassionati del minimalismo, c'è un installer pronto per Linux che registra LeafWiki come servizio di sistema:

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

Lavorare da dispositivi mobili

L'interfaccia è responsive. Modificare il testo da un telefono è un piacere discutibile, ma leggere documentazione in movimento o correggere rapidamente un errore di battitura è perfettamente fattibile.

LeafWiki conquista con la sua prevedibilità. È perfetta per:

• Un diario tecnico personale o una knowledge base.
• Documentazione per un progetto piccolo.
• Runbook interni per admin o ingegneri DevOps.

Se sei stanco di combattere con motori wiki pesanti e vuoi semplicemente scrivere Markdown che viene organizzato ordinatamente — prova questo progetto. Attualmente ha meno di mille stelle su GitHub, ma ha sicuramente il potenziale per diventare "quel semplice strumento" che cercavi.