---
title: Introducere & Model Mental
description: Filosofia, principiile de design și modelul mental al VertiWiki, motorul de documentație static într-un singur fișier.
tags: [vertiwiki, introducere, filosofie, model-mental, zero-backend, romana]
---

# Introducere în VertiWiki

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

VertiWiki este un motor modern de documentație tehnică și wiki Markdown, 100% static, compactat într-un singur fișier. Acesta oferă ergonomia portalurilor enterprise de documentație fără a necesita lanțuri complexe de compilare, servere de fundal, baze de date sau recompilări la fiecare actualizare de conținut.

---

## 💡 Problema de Bază

Framework-urile tradiționale de documentație (precum Docusaurus, VitePress sau MkDocs) depind de generarea statică ahead-of-time (AOT):

1. **Pipeline-uri de Build Greoaie**: Orice corectură sau adăugare de pagină Markdown impune rularea unui build CI Node.js sau Python, descărcarea a sute de megabytes de dependențe și recompilarea pachetelor statice.
2. **Costuri Operaționale**: Alternativele self-hosted (cum ar fi Wiki.js sau BookStack) necesită servere active (Node/PHP), baze de date relaționale (PostgreSQL/MySQL), backup-uri planificate și întreținere continuă de securitate.
3. **Fricțiune la Implementare**: Creatorii de conținut nu pot pur și simplu adăuga fișiere Markdown într-un bucket S3, Cloudflare Pages sau server web static fără a declanșa o compilare.

---

## 🧠 Modelul Mental VertiWiki

VertiWiki inversează această paradigmă:

```mermaid
graph LR
    subgraph SSG Tradițional
        A[Sursă Markdown] --> B[Server Build CI Node/Python]
        B --> C[Pachet HTML/CSS Compilat]
        C --> D[CDN / Edge]
    end

    subgraph Paradigma VertiWiki
        E[Sursă Markdown] --> F[Server Web Static]
        G[Fișier Unic vertiwiki.html] --> F
        F --> H[Execuție Runtime în Browser]
    end
```

### 1. Motorul ca un Singur Element
Întreaga interfață de utilizator, extensiile de parsare, evidențierea sintaxei, indexul de căutare și motorul de teme sunt compilate într-un singur fișier HTML de distribuție (`dist/vertiwiki.html` sau `index.html`).

### 2. Preluare & Randare Live la Runtime
Când un cititor accesează o adresă URL precum `https://my-wiki.internal/#/guides/getting-started.md`:
- Motorul client interceptează ruta hash.
- Execută un apel asincron HTTP `fetch` pentru a descărca documentul Markdown solicitat.
- Pipeline-ul procesează frontmatter-ul, transformă wikilink-urile, compilează blocurile de cod cu Prism.js, igienizează codul HTML prin DOMPurify și montează documentul în DOM.
- Plugin-ul de căutare construiește un index inversat în memorie folosind MiniSearch pentru filtrare instantanee.

### 3. Fără Compilare la Modificarea Conținutului
Editarea documentației înseamnă doar modificarea fișierului Markdown. Următoarea reîmprospătare a paginii în browser reflectă instantaneu modificările.

---

## 🎯 Principii de Design

- **Invariantul Zero-Backend**: Niciun proces Node.js, runtime Python sau bază de date nu este necesar în producție. Serverele HTTP standard servesc fișierele direct.
- **Securitate Client-Side Implicită**: Fiecare fragment Markdown trece printr-un profil securizat DOMPurify înainte de a fi introdus în DOM.
- **Rutare Deterministă Profundă**: Linkurile directe, găzduirea în subdirectoare și traducerile localizate (`en`, `ro`, `fr`) sunt gestionate determinist prin rute hash client (`/#/guide.md` sau `/#/ro/guide.md`).
- **Compatibilitate cu Agenți AI (AEO)**: Suport nativ pentru `llms.txt`, negociere de conținut Markdown curat și structuri semantice accesibile direct asistenților autonomi de codare.
- **Decuplarea Token-urilor de Design**: Identitatea vizuală este gestionată prin variabile CSS și preseturi JSON ușoare (`themes/obsidian.json`, `themes/dracula.json`) fără a modifica codul JavaScript de bază.

---

## 🔗 Pașii Următori

- Începeți configurarea practică prin [Ghidul Rapid de 5 Minute](quickstart.md).
- Descoperiți formatele de distribuție și instalare în [Instalare & Configurare](installation.md).
- Înțelegeți funcționarea internă în [Ghidul de Arhitectură](concepts/architecture.md).