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 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
