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,98 @@
+# MarkdownRender (CLI `md-render`)
+
+`MarkdownRender-nodejs` est un **outil en ligne de commande** indépendant de l'application
+Tauri. Il convertit du Markdown en HTML et propose une prévisualisation live dans le
+navigateur. Il est utile pour générer rapidement un `.html` ou prévisualiser un document sans
+lancer Pena.
+
+> C'est un utilitaire **annexe** ; le produit principal reste
+> [Pena-tauri](../2-technique/2.1-Architecture.md).
+
+## Installation
+
+Prérequis : **Node.js** (avec `npm`).
+
+Depuis `MarkdownRender-nodejs/` :
+```bash
+npm install
+npm link   # rend la commande `md-render` disponible globalement
+```
+
+## Utilisation
+
+```bash
+# Conversion simple (génère un fichier .html à côté de l'entrée)
+md-render README.md
+
+# Conversion vers un fichier de sortie précis
+md-render README.md -o documentation.html
+
+# Mode preview — ouvre le navigateur sans créer de fichier
+md-render README.md --preview
+
+# Preview d'un dossier entier (avec barre latérale)
+md-render mon-wiki/ --preview
+
+# Mode watch — sert http://localhost:3000 avec rechargement automatique
+md-render README.md --watch
+
+# Sur un port personnalisé
+md-render README.md --watch --port 8080
+```
+
+## Options
+
+| Option | Alias | Description | Défaut |
+|---|---|---|---|
+| `--watch` | `-w` | Démarre un serveur avec rechargement automatique | — |
+| `--preview` | `-v` | Ouvre dans le navigateur sans créer de fichier | — |
+| `--port <port>` | `-p` | Port du serveur (watch ou preview) | `3000` |
+| `--output <fichier>` | `-o` | Fichier HTML de sortie | `<entrée>.html` |
+| `--help` | `-h` | Affiche l'aide | — |
+
+## Modes
+
+### Mode preview (`--preview`)
+Le Markdown est converti **en mémoire** et affiché directement dans le navigateur — aucun
+fichier HTML n'est écrit sur le disque. Le navigateur s'ouvre automatiquement.
+`Ctrl+C` arrête le serveur. Fonctionne sur un fichier unique ou un dossier entier.
+
+### Mode watch (`--watch`)
+Un serveur HTTP local est démarré. À chaque sauvegarde du fichier, la page se recharge
+automatiquement via **Server-Sent Events (SSE)**. Les assets relatifs (images…) placés dans
+le même répertoire que le `.md` sont servis automatiquement.
+
+## Fonctionnalités
+
+- 🎨 Coloration syntaxique du code ([highlight.js](https://highlightjs.org/))
+- 📄 Rendu de style « GitHub-like »
+- 👁 Prévisualisation instantanée sans fichier (`--preview`)
+- 🔄 Rechargement automatique en mode watch (SSE)
+- 🖼 Serveur de fichiers statiques pour les images locales
+- ⚡ Débounce intelligent pour éviter les rechargements en rafale
+- 🛡 Protection contre le path traversal
+
+## Dépendances principales
+
+| Paquet | Rôle |
+|---|---|
+| [`marked`](https://marked.js.org/) | Conversion Markdown → HTML |
+| `marked-highlight` + [`highlight.js`](https://highlightjs.org/) | Coloration syntaxique |
+| [`chokidar`](https://github.com/paulmillr/chokidar) | Surveillance de fichiers (mode watch) |
+| [`minimist`](https://github.com/minimistjs/minimist) | Analyse des arguments CLI |
+
+## Différences avec Pena-tauri
+
+| | `md-render` (CLI) | Pena-tauri (app) |
+|---|---|---|
+| Plateforme | Terminal + navigateur | Application de bureau |
+| Rendu Markdown | `marked` (JS) | `comrak` (Rust) |
+| Coloration | highlight.js | syntect |
+| Live-reload | ✅ (SSE) | implémenté mais non branché |
+| Thèmes / CSS éditable | — | ✅ |
+| Sortie fichier HTML | ✅ | — |
+
+## Voir aussi
+
+- [Vue d'ensemble de Pena](../1-fonctionnel/1.1-Vue-d-ensemble.md)
+- [README de la documentation](../README.md)