---
title: Introduction & Modèle Mental
description: Philosophie, principes de conception et modèle mental de VertiWiki, le moteur de documentation statique en un seul fichier.
tags: [vertiwiki, introduction, philosophie, modele-mental, zero-backend, francais]
---

# Introduction à VertiWiki

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

VertiWiki est un moteur de documentation technique et wiki Markdown moderne, 100% statique et condensé en un seul fichier HTML. Il offre l'ergonomie des portails documentaires d'entreprise sans imposer de chaînes de compilation complexes, de processus serveur d'arrière-plan, de bases de données ou de redéploiements lors des mises à jour textuelles.

---

## 💡 Le Problème Fondamental

Les frameworks documentaires traditionnels (tels que Docusaurus, VitePress ou MkDocs) reposent sur la génération de sites statiques ahead-of-time (AOT) :

1. **Pipelines de Compilation Lourds** : La moindre correction orthographique impose de relancer un build CI Node.js ou Python, d'installer des centaines de mégaoctets de dépendances et de recompiler l'ensemble du site.
2. **Charges Opérationnelles** : Les solutions auto-hébergées (comme Wiki.js ou BookStack) nécessitent des serveurs applicatifs actifs (Node/PHP), des bases de données relationnelles (PostgreSQL/MySQL), des sauvegardes régulières et une maintenance de sécurité permanente.
3. **Friction de Déploiement** : Les rédacteurs ne peuvent pas simplement transférer un fichier Markdown sur un bucket S3, Cloudflare Pages ou un serveur web statique et observer le résultat sans déclencher un processus de build.

---

## 🧠 Le Modèle Mental VertiWiki

VertiWiki inverse cette approche :

```mermaid
graph LR
    subgraph SSG Traditionnel
        A[Fichier Markdown] --> B[Serveur CI Node/Python]
        B --> C[Paquet HTML/CSS Compilé]
        C --> D[CDN / Edge]
    end

    subgraph Paradigme VertiWiki
        E[Fichier Markdown] --> F[Serveur Web Statique]
        G[Fichier Unique vertiwiki.html] --> F
        F --> H[Exécution dans le Navigateur]
    end
```

### 1. Le Moteur sous Forme d'Actif Unique
L'intégralité de l'interface utilisateur, des analyseurs Markdown, de la coloration syntaxique, de l'indexation de recherche et du moteur de thèmes est compilée dans une distribution HTML unique (`dist/vertiwiki.html` ou `index.html`).

### 2. Récupération & Rendu Dynamiques à l'Exécution
Lorsqu'un utilisateur accède à une URL comme `https://my-wiki.internal/#/guides/getting-started.md` :
- Le routeur client intercepte le hash de l'URL.
- Il déclenche un appel asynchrone HTTP `fetch` pour récupérer le document Markdown demandé.
- Le pipeline extrait les métadonnées frontmatter, transforme les wikilinks, compile le code avec Prism.js, assainit le code HTML via DOMPurify et monte le contenu dans le DOM.
- Le moteur de recherche indexe en mémoire le texte brut via MiniSearch pour une recherche plein texte instantanée.

### 3. Zéro Compilation lors de la Modification de Contenu
Pour mettre à jour la documentation, il suffit d'éditer le fichier Markdown. Le rafraîchissement du navigateur affiche immédiatement les modifications.

---

## 🎯 Principes Clés de Conception

- **Invariant Zéro-Backend** : Aucun runtime Node.js ou base de données n'est requis en production. Les serveurs web HTTP standards distribuent les fichiers directement.
- **Sécurité Côté Client par Défaut** : Chaque fragment Markdown est assaini par DOMPurify avant son insertion dans le DOM, neutralisant les vecteurs XSS.
- **Routage Déterministe et Profond** : Les liens profonds, déploiements en sous-dossiers et versions multilingues (`en`, `ro`, `fr`) sont gérés de façon déterministe via les routes hash (`/#/guide.md` ou `/#/fr/guide.md`).
- **Compatibilité IA (AEO)** : Prise en charge native de `llms.txt`, négociation de contenu pour agents IA et balisage sémantique clair.
- **Découplage des Jetons de Design** : L'identité graphique est configurée via des propriétés CSS personnalisées et des fichiers JSON légers (`themes/obsidian.json`, `themes/dracula.json`) sans toucher au code JavaScript.

---

## 🔗 Prochaines Étapes

- Commencez tout de suite avec le [Guide de Démarrage en 5 Minutes](quickstart.md).
- Découvrez les modes d'installation dans [Installation & Configuration](installation.md).
- Explorez l'architecture détaillée dans le [Guide d'Architecture Système](concepts/architecture.md).