Spaces:
Sleeping
Sleeping
File size: 8,241 Bytes
898ed62 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 | # PRD — MarkitDown Local WebApp
**Version** : 1.0
**Date** : 11 mai 2026
**Statut** : Finalisé
---
## 1. Contexte & Objectif
### Problème
Convertir des fichiers (PDF, Word, Excel, PowerPoint, images, HTML…) en Markdown est une tâche fréquente mais fastidieuse en ligne de commande. La librairie [MarkItDown](https://github.com/microsoft/markitdown) de Microsoft résout la conversion, mais elle reste inaccessible sans interface.
### Objectif
Créer une **application web locale** minimaliste, lancée en **un double-clic** sur un fichier `.bat` (Windows) ou `.sh` (Mac/Linux), qui expose MarkItDown dans un navigateur sans aucune étape de build préalable.
---
## 2. Utilisateurs cibles
- Développeurs, tech writers, data analysts souhaitant convertir rapidement des fichiers locaux
- Utilisateurs non-techniques voulant un outil simple sans setup complexe
- Profil principal : utilisateur unique en local (pas de multi-tenant)
---
## 3. Périmètre fonctionnel
### 3.1 Fonctionnalités — Must Have 🔴
| ID | Fonctionnalité | Description |
|----|---------------|-------------|
| F1 | Upload de fichier | Drag & drop + bouton "Parcourir". Un ou plusieurs fichiers à la fois |
| F2 | Conversion Markdown | Via MarkItDown — tous les formats supportés (PDF, DOCX, PPTX, XLSX, images, HTML, CSV, JSON, ZIP…) |
| F3 | Prévisualisation | Affichage du Markdown rendu (HTML) et du Markdown brut (code) en onglets |
| F4 | Téléchargement `.md` | Bouton "Télécharger" → génère un fichier `.md` nommé d'après le fichier source |
| F5 | Copie presse-papier | Bouton "Copier" → copie le Markdown brut dans le clipboard |
| F6 | Lancement 1 clic | Fichier `start.bat` (Windows) et `start.sh` (Mac/Linux) qui installent les dépendances si absent et lancent l'app |
### 3.2 Fonctionnalités — Should Have 🟠
| ID | Fonctionnalité | Description |
|----|---------------|-------------|
| F7 | Historique local | Liste des dernières conversions (nom fichier, date, taille MD) persistée dans un fichier JSON local |
| F8 | Re-téléchargement | Depuis l'historique, re-télécharger ou re-copier un résultat précédent |
| F9 | Batch conversion | Convertir plusieurs fichiers en une fois, télécharger un `.zip` des `.md` résultants |
### 3.3 Fonctionnalités — Nice to Have 🟡
| ID | Fonctionnalité | Description |
|----|---------------|-------------|
| F10 | Conversion URL | Saisir une URL à la place d'un fichier — MarkItDown supporte le scraping HTML |
| F11 | Effacer historique | Bouton pour vider l'historique |
---
## 4. Architecture technique
### Stack
- **Backend** : Python + **Flask** (léger, zéro config, idéal pour usage local)
- **Frontend** : HTML/CSS/JS vanilla — pas de framework, pas de build step
- **Conversion** : `markitdown` (pip)
- **Persistance** : fichier `history.json` local dans le dossier de l'app
### Structure du projet
```
markitdown-app/
├── start.bat ← Lancement Windows (double-clic)
├── start.sh ← Lancement Mac/Linux
├── app.py ← Serveur Flask
├── requirements.txt ← markitdown, flask
├── history.json ← Historique (créé auto au premier lancement)
├── static/
│ ├── style.css
│ └── script.js
└── templates/
└── index.html
```
### Logique du launcher (`start.bat`)
```
1. Vérifie si Python est installé → sinon, message d'erreur clair
2. Vérifie si le venv existe → sinon, le crée et installe requirements.txt
3. Active le venv
4. Lance app.py (Flask sur http://localhost:5000)
5. Ouvre automatiquement le navigateur sur http://localhost:5000
```
---
## 5. Interface utilisateur
### Principes
- Simple, minimaliste, sobre — aucun framework CSS externe
- Palette monochrome (blanc/gris) + une couleur d'accent (violet ou indigo)
- Responsive (fonctionne de 800px à 1400px)
- Pas de dark mode (hors scope v1)
### Layout
```
┌─────────────────────────────────────────────────┐
│ MarkitDown [historique] │
├─────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────┐ │
│ │ Glissez un fichier ici │ │
│ │ ou cliquez pour parcourir │ │
│ └────────────────────────────────────────┘ │
│ │
│ [Rendu] [Markdown brut] │
│ ┌────────────────────────────────────────┐ │
│ │ (prévisualisation du résultat) │ │
│ └────────────────────────────────────────┘ │
│ │
│ [⬇ Télécharger .md] [⎘ Copier] │
│ │
├─────────────────────────────────────────────────┤
│ Historique nom_fichier.pdf 12/05 [↓] [⎘] │
│ autre_fichier.docx 11/05 [↓] [⎘] │
└─────────────────────────────────────────────────┘
```
---
## 6. Formats supportés
Tous les formats pris en charge par MarkItDown :
| Catégorie | Formats |
|-----------|---------|
| Documents Office | `.docx`, `.pptx`, `.xlsx` |
| PDF | `.pdf` |
| Images | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp` |
| Web | `.html`, `.htm` |
| Données | `.csv`, `.json`, `.xml` |
| Archives | `.zip` (extrait et convertit le contenu) |
| Texte | `.txt`, `.md`, `.rst` |
| Code | tous types de fichiers texte |
| Audio | `.mp3`, `.wav` (transcription via MarkItDown si ffmpeg disponible) |
---
## 7. Gestion des erreurs
| Cas | Comportement attendu |
|-----|---------------------|
| Format non supporté | Message d'erreur inline dans l'UI : "Format non supporté par MarkItDown" |
| Fichier corrompu | Message d'erreur avec détail de l'exception Python |
| Python non installé | Le `.bat` affiche une fenêtre CMD avec instruction d'installation |
| Port 5000 occupé | Flask essaie le port 5001, puis 5002 — affiche le port utilisé |
| Fichier trop lourd (>50 Mo) | Warning dans l'UI, conversion lancée quand même |
---
## 8. Contraintes & non-objectifs
- ❌ Pas de déploiement cloud (100% local)
- ❌ Pas d'authentification (usage solo)
- ❌ Pas de dark mode en v1
- ❌ Pas d'installeur `.exe` (le `.bat` suffit)
- ✅ Fonctionne offline (zéro appel réseau une fois les dépendances installées)
- ✅ Python 3.9+ requis (documenté dans le README)
---
## 9. Livrables
| Livrable | Description |
|----------|-------------|
| `start.bat` + `start.sh` | Launchers prêts à l'emploi |
| `app.py` | Backend Flask complet |
| `index.html` + `style.css` + `script.js` | Frontend complet |
| `requirements.txt` | `flask`, `markitdown` |
| `README.md` | Instructions : prérequis Python, comment lancer, formats supportés |
---
## 10. Critères d'acceptation
- [ ] Double-clic sur `start.bat` → navigateur s'ouvre sur l'app en moins de 15 secondes (premier lancement)
- [ ] Double-clic sur `start.bat` → app lance en moins de 3 secondes (lancements suivants)
- [ ] Upload d'un PDF → Markdown correct affiché en moins de 10 secondes
- [ ] Bouton "Télécharger" → fichier `.md` téléchargé avec le bon nom
- [ ] Bouton "Copier" → contenu dans le clipboard
- [ ] La conversion est visible dans l'historique après chaque succès
- [ ] L'historique persiste après fermeture et réouverture de l'app |