docs: documentation fonctionnelle, technique et installation

2026-07-05 10:58:29 +02:00
parent 61fb56fa14
commit 64c53f412d
12 changed files with 1452 additions and 0 deletions
@@ -0,0 +1,58 @@
+# Vue d'ensemble
+
+## Qu'est-ce que Pena ?
+
+Pena est un **lecteur Markdown de bureau**. Son objectif est d'offrir une lecture confortable
+de documentation écrite en Markdown, qu'il s'agisse d'un fichier unique (un `README.md`) ou
+d'un ensemble de fichiers organisés en arborescence (un « wiki » de documentation).
+
+Contrairement à un éditeur, Pena est **focalisé sur la lecture** : il n'édite pas les fichiers,
+il les affiche joliment, permet de naviguer entre eux, et de personnaliser entièrement
+l'apparence du rendu.
+
+## Pour qui ?
+
+- Toute personne qui consulte régulièrement de la documentation Markdown en local
+  (wikis de projet, notes, documentation technique).
+- Les utilisateurs qui veulent un rendu plus agréable et configurable que l'aperçu brut
+  d'un éditeur de texte.
+- Ceux qui maintiennent une documentation multi-fichiers organisée en dossiers et
+  sous-dossiers, et qui veulent naviguer dedans comme dans un wiki.
+
+## Deux modes d'ouverture
+
+Pena propose deux façons d'ouvrir du contenu :
+
+| Mode | Déclencheur | Comportement |
+|---|---|---|
+| **Fichier** | « Ouvrir un fichier Markdown » | Ouvre un `.md` isolé. La barre latérale liste tous les `.md` du dossier parent pour faciliter la navigation. |
+| **Dossier (wiki)** | « Ouvrir un dossier wiki » | Ouvre un dossier complet. Tous les `.md` (y compris dans les sous-dossiers) sont listés en arborescence. Si un fichier `Home.md` existe, il est affiché en premier. |
+
+## Principes de fonctionnement
+
+- **Rendu côté Rust** — La conversion Markdown → HTML est faite par le backend Rust
+  (`comrak`), pas par une bibliothèque JS. Cela garantit un rendu rapide et cohérent.
+- **CommonMark + extensions** — Les tableaux, le texte barré, les liens automatiques et les
+  listes de tâches sont pris en charge.
+- **Coloration syntaxique** — Les blocs de code sont colorés via `syntect`, avec un thème
+  de coloration intégré (`base16-ocean.dark`).
+- **Navigation entre documents** — Les liens Markdown relatifs entre fichiers
+  (ex. `[voir](../autre/page.md)`) sont fonctionnels : cliquer dessus charge le document
+  cible dans Pena.
+- **Tout reste local** — Aucune connexion réseau n'est nécessaire. Les préférences
+  (récents, thème, CSS personnalisé) sont stockées localement dans le navigateur embarqué
+  (localStorage).
+
+## Ce que Pena ne fait pas (encore)
+
+- Pas d'édition de fichiers Markdown (lecture seule).
+- Pas de rechargement automatique à la modification du fichier : le mécanisme de
+  surveillance (« watcher ») existe côté backend mais n'est pas branché côté interface.
+  Voir [Commandes Tauri](../2-technique/2.2-Commandes-Tauri.md#surveillance-de-fichiers-watch).
+
+## Voir aussi
+
+- [Fonctionnalités détaillées](1.2-Fonctionnalites.md)
+- [Interface](1.3-Interface.md)
+- [Thèmes et personnalisation](1.4-Themes-et-personnalisation.md)
+- [Architecture technique](../2-technique/2.1-Architecture.md)