Spaces:
Sleeping
Sleeping
| # 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 |