Spaces:

Gauthier76
/

Markdown

Sleeping

GauthierDemonchy

Premier commit propre

898ed62 5 months ago

8.24 kB

# 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

	# 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