# 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