Toate soluțiile de documentație erau prea greoaie, așa că mi-am construit propriul motor: VertiWiki

De fiecare dată când ai de structurat documentația unui proiect, procedurile interne ale unei echipe sau un manual tehnic complet, opțiunile existente te împing într-un compromis prost.

Ori ajungi la un generator static clasic care vine la pachet cu un munte de dependențe și pipeline-uri CI/CD unde o corectură de literă durează trei minute de build, ori ridici un server dedicat cu bază de date și mentenanță continuă, ori apelezi la platforme moderne de documentație în cloud care încep să-ți ceară sute de dolari pe lună imediat ce ai nevoie de un domeniu propriu sau documente interne. Când vrei doar să pui fișiere Markdown într-un folder și să ai instant un wiki curat, rapid și plăcut de citit, opțiunile devin brusc foarte subțiri.

Am trecut prin majoritatea uneltelor consacrate. Docusaurus, VitePress și Starlight sunt solide, dar complexitatea lor de build devine obositoare când nu vrei să configurezi un întreg ecosistem Node doar pentru a reda câteva fișiere text. Pe cealaltă parte, soluțiile clasice cu backend precum BookStack sau DokuWiki cer găzduire cu PHP/baze de date și actualizări constante de securitate. Iar uneltele client-side mai vechi, de tip Docsify, au rămas ancorate într-o arhitectură fragilă, fără o tipografie cu adevărat lizibilă, fără teme decuplate și total deconectate de la felul în care utilizăm documentația astăzi, când o bună parte din căutări și interogări sunt intermediate de agenți AI.

Așa că am decis să-mi construiesc propriul motor de documentație și wiki: VertiWiki (open-source pe GitHub).

Zero servere, zero baze de date, zero timp de build

Salvezi fișierul Markdown și conținutul este live pe ecran

Miezul VertiWiki este simplitatea absolută a distribuției. Tot motorul rulează direct în browser, pe bază de JavaScript client-side modern compilat cu Vite și TypeScript, fără a avea nevoie de vreun backend sau de procese server-side de regenerare la fiecare modificare de conținut.

Distribuția este de tip single-file: un singur fișier vertiwiki.html (sau redenumit index.html) plasat lângă fișierele tale Markdown (index.md, navigation.md, config.json). Când modifici un fișier .md, nu declanșezi un webhook de build și nu aștepți după un runner GitHub Actions sau Vercel. Dai refresh și documentul actualizat este acolo, parsat curat, cu navigare instantanee și căutare indexată pe loc.

Dacă vrei să găzduiești documentația, o poți urca pe orice spațiu de stocare static: GitHub Pages, Cloudflare Pages, Vercel, un bucket S3 sau un simplu server Nginx. Iar dacă vrei să consulți un wiki intern offline sau într-o rețea complet izolată, fișierul funcționează direct de pe disc.

De ce VertiWiki este o alternativă mai sănătoasă la Mintlify

Design modern fără abonament lunar și fără blocaj în componente proprietare

În ultimii doi ani, Mintlify a devenit standardul de facto pentru documentația multor startup-uri tehnice. Arată foarte bine, are un stil vizual lustruit și o tipografie îngrijită. Însă în spatele acelei fațade se ascund trei mari probleme de arhitectură și costuri:

1. Modelul comercial SaaS și taxarea pe funcționalități de bază: Mintlify te ademenește cu un nivel gratuit, dar în momentul în care ai nevoie de un domeniu personalizat fără branding terț, de documentație privată pentru echipă, de autentificare sau de analiză avansată, sari direct la planuri de 150–400+ dolari pe lună. Pentru multe firme mici, proiecte open-source sau echipe operaționale, să plătești mii de dolari pe an doar ca să afișezi câteva pagini de proceduri este o cheltuială nejustificată.
2. Lock-in prin sintaxă proprietară MDX: Mintlify te obligă să-ți împânzești documentele cu taguri specifice de componente (<CardGroup>, <ParamField>, <Tip>). Dacă peste un an decizi să pleci de la ei, fișierele tale nu mai sunt Markdown standard; sunt o colecție de componente proprietare care nu mai pot fi deschise curat în Obsidian, pe GitHub sau într-un alt editor fără o muncă titanică de curățare manuală. VertiWiki folosește Markdown standard (CommonMark / GFM) și Wikilinks native ([[pagina]]), păstrând compatibilitatea 100% cu vault-urile de Obsidian și orice vizualizator de text.
3. Suveranitatea datelor și confidențialitatea: Pentru documentație publică de API, un serviciu cloud precum Mintlify e acceptabil. Dar când scrii proceduri operaționale interne (SOP-uri), arhitecturi interne de rețea, scheme de baze de date sau proceduri confidențiale de companie, nu vrei ca acele date să tranziteze sau să fie găzduite pe serverele unui furnizor extern. Cu VertiWiki, datele tale rămân în Git-ul tău, găzduite pe propria infrastructură statică sau chiar pe un intranet intern complet deconectat de la internet.

VertiWiki oferă aceeași eleganță vizuală și aceeași viteză pe care oamenii o caută la Mintlify, dar o face sub o licență MIT 100% gratuită, cu zero dependențe de cloud terț.

Butonul Copy AI și consumul documentației în 2026

Utilizatorul nu mai citește doar manual, ci interoghează conținutul

Unul dintre motivele majore pentru care am vrut un motor nou a fost schimbarea de comportament a celor care citesc documentație. În prezent, un inginer, un manager operațional sau un utilizator curios nu mai parcurge întotdeauna pagini dense de la un capăt la altul; adesea vrea să ia contextul unei pagini tehnice și să-l plaseze într-un asistent AI pentru a adresa întrebări specifice pe procedurile descrise.

În VertiWiki, fiecare pagină are implicit în bara de sus butonul „Copy for AI”. Cu un singur click, întregul conținut al paginii este curățat de elemente de interfață sau zgomot vizual și copiat direct în clipboard ca Markdown structurat. De acolo, îl poți trimite direct într-o fereastră de Claude, ChatGPT, Perplexity sau un agent local ca să pui întrebări precum „Care sunt excepțiile de la această regulă?” sau „Generează configurația pentru cazul X pe baza acestui ghid”.

Multe platforme comerciale (inclusiv Mintlify) taxează suplimentar sau restricționează la abonamente enterprise funcțiile de asistență AI. În VertiWiki, filozofia este inversă: îți oferim conducta nativă de date direct în clipboard, permițându-ți să folosești propriul tău model sau asistent preferat, fără intermediari și fără costuri adăugate.

Funcția este activată nativ, dar poate fi dezactivată printr-o simplă cheie în config.json ("enableAiCopy": false) dacă documentația se adresează unui public strict non-tehnic.

Arhitectură pregătită nativ pentru AEO

Răspunsuri pentru crawlere și interfață pentru oameni

VertiWiki a fost construit cu gândul la Answer Engine Optimization (AEO). Nu este suficient ca o pagină să fie vizibilă în motoarele de căutare tradiționale; motoarele de răspunsuri și asistenții autonomi de cod (Claude Code, Cursor, Aider, OpenCode) trebuie să poată citi conținutul fără să fie blocați de scheletul JavaScript al unui SPA.

Pentru a rezolva această tensiune, VertiWiki folosește câteva mecanisme specifice:

• Negociere de conținut pe server: Dacă o cerere HTTP include antetul Accept: text/markdown, serverul livrează direct fișierul .md brut. Când cererea vine dintr-un browser obișnuit, se încarcă interfața completă.
• Index standardizat pentru LLM-uri: Generare automată de referințe către llms.txt, astfel încât asistenții AI să aibă o hartă precisă a întregului wiki dintr-o singură cerere.
• Arbore semantic pentru crawlere: Una dintre problemele recurente ale aplicațiilor client-side (SPA) în Google Search Console este starea de „Discovered - currently not indexed”. VertiWiki include un arbore semantic static (<nav class="verti-crawl-tree">) care expune toate ancorele de navigare direct în HTML-ul inițial, eliminând paginile orfane.
• Grafuri JSON-LD: Date structurate Schema.org injectate dinamic pentru breadcrumbs și ierarhia documentelor.

Ergonomie de lectură și teme complet decuplate

De la documentație de API la cărți și manuale de politici

Majoritatea temelor de wiki sunt proiectate exclusiv pentru biblioteci de cod: linii lungi, ecrane aglomerate de panouri laterale și fonturi înghesuite. Când vrei să publici proceduri operaționale standard (SOP), politici de companie sau ghiduri de onboarding, ochii obosesc după cinci minute.

În VertiWiki am introdus parametrul de ergonomie contentWidth: "readable". Acesta fixează lățimea textului la 68 de caractere pe linie și crește înălțimea rândului la 1.8, oferind un ritm de lectură apropiat de cel al unei cărți tipărite.

Mai mult, motorul suportă mai multe layout-uri prin atributul data-layout (default, book, handbook, api, hub), care pot fi aplicate global sau per pagină prin Frontmatter (layout: book). Dacă o pagină este o simplă descriere de politică internă, modul book ascunde panoul Table of Contents și centrează textul. Dacă este un endpoint tehnic, modul api extinde lățimea pentru tabele și blocuri paralele de cod.

Temele vizuale sunt complet decuplate în fișiere JSON independente (themes/obsidian.json, themes/editorial.json, themes/nord.json, themes/onyx-ops.json). Nu rescrii CSS-ul motorului ca să schimbi paleta; adaugi un fișier JSON cu variabilele de culoare și îl referențiezi în config.json.

Cum se compară cu alternativele consacrate

Uneltele existente și nișa pe care o rezolvă VertiWiki

Pe AlternativeTo, VertiWiki este poziționat în mod natural alături de generatoarele mari de documentație. Diferențele practice țin de filosofia de funcționare:

Criteriu	VertiWiki	Mintlify	Docusaurus / Starlight	Docsify	GitBook / Notion
Model & Licență	Open Source (MIT)	SaaS Comercial închis	Open Source	Open Source	SaaS Comercial închis
Cost lunar	Zero	150$ – 400$+ / lună	Zero	Zero	Abonament per user
Infrastructură	100% static, client-side	Cloud proprietar	Node.js build pipeline	Client-side SPA	Cloud proprietar
Editare conținut	Salvezi .md, gata	Git push $\rightarrow$ Cloud parse	Recompilare / CI/CD	Salvezi .md, gata	În aplicație web
Format fișiere	Markdown pur + Wikilinks	MDX cu componente proprii	MDX / Markdown	Markdown	Format proprietar
Distribuție	Fișier unic (vertiwiki.html)	Servit de cloud Mintlify	Bundle de sute de fișiere	Scripturi JS multiple	Web app închisă
Pregătire AEO / AI	Nativ (Copy AI, llms.txt)	Addon comercial plătit	Doar prin plugin-uri	Nu	Parțial / proprietar
Securitate & Date	Suveranitate 100%, DOMPurify	Date găzduite la terți	Zero baze de date	Vulnerabilități istorice	Controlat de furnizor

Față de Mintlify, scapi de taxele lunare exorbitante și de blocajul în componente MDX pe care nu le poți porta în altă parte. Față de Docusaurus sau VitePress, elimini faza de build la fiecare modificare de text. Iar față de Docsify, beneficiezi de o platformă TypeScript modernă, cu securitate garantată împotriva atacurilor XSS prin DOMPurify, teme decuplate și un design contemporan.

Cum pornești un wiki în două minute

Structura minimă a directorului

Dacă vrei să rulezi VertiWiki pe propriul tău set de documente, ai nevoie doar de câteva fișiere într-un director:

my-docs/
├── vertiwiki.html     # Redenumit în index.html dacă vrei să fie rădăcina
├── config.json        # Setările de titlu, temă și limbi
├── navigation.md      # Structura meniului lateral în markdown
└── index.md           # Pagina principală

Fișierul config.json conține opțiunile de bază:

{
  "title": "Documentație Internă",
  "theme": "onyx-ops",
  "enableAiCopy": true,
  "contentWidth": "readable",
  "locales": ["ro", "en"]
}

Iar fișierul navigation.md este o simplă listă Markdown cu linkuri:

- [Acasă](index.md)
- Ghiduri Operaționale
  - [Proceduri de Lucru](docs/proceduri.md)
  - [Securitate și Acces](docs/securitate.md)
- [Contact](docs/contact.md)

Totul este gata. Nu există pași ascunși de configurare, pachete npm de instalat pentru redare sau baze de date de legat.

Unde nu este VertiWiki soluția potrivită

Limitările asumate ale unui motor exclusiv static

Ar fi necinstit să spun că o astfel de arhitectură acoperă orice scenariu. VertiWiki nu este un CMS pentru echipe mari care au nevoie de editare colaborativă simultană în stil Google Docs direct în interfața web și nici nu include un sistem de permisiuni granulare pe utilizatori (ACL) stocate pe un server central. Pentru baze de date de cunoștințe corporative unde zeci de departamente au nevoie de fluxuri de aprobare și login prin Active Directory, platforme precum Confluence sau BookStack își au rolul lor.

VertiWiki este calibrat pentru ingineri, fondatori, echipe agile, consultanți operaționali sau proiecte open-source care vor să-și stăpânească datele în fișiere text pure, controlate prin Git, cu o interfață la nivelul anului 2026 și zero dureri de cap legate de mentenanța serverelor sau facturi lunare de SaaS.

Documentația trebuie să fie un activ, nu o povară

Menținerea lucrurilor cât mai simple

Cea mai bună documentație este aceea care se citește ușor și se actualizează fără efort. În momentul în care adăugarea unei proceduri noi necesită rularea de scripturi complexe de compilare sau plata unor abonamente scumpe către terți, echipele renunță să o mai scrie.

Prin VertiWiki, am adus documentația exact la acest nivel de fluență: un fișier Markdown salvat pe disc este imediat accesibil pentru echipă, pregătit pentru căutare și direct utilizabil de către agenții AI.