docboard

Un viewer documentaire local, léger, portable et réutilisable : ouvre n'importe quel dossier de projet dans un navigateur, navigue dans l'arborescence, lis le markdown rendu proprement, prévisualise les PDF, HTML, images, audios, vidéos — sans éditeur, sans build, sans dépendance à installer.

Stack : un seul fichier HTML + un petit serveur Python stdlib (aucun pip install, aucun npm install). Fonctionne hors ligne, sauf pour le premier chargement des CDN CSS/JS (marked, highlight.js, github-markdown-css) qui sont mis en cache par le navigateur.

Fonctionnalités

• Arborescence auto-découverte — scanne le dossier à chaque requête, pas de manifest à regénérer
• Rendu markdown riche — GFM, tables, checkboxes, code coloré, blockquotes, emojis
• Prévisualisations inline — PDF, HTML, images, audio, vidéo, texte brut
• Recherche plein-texte dans tous les .md avec surlignage
• Mode clair / sombre mémorisé
• Liens internes résolus — les [ref](./autre.md) ouvrent directement le doc cible
• Breadcrumb cliquable
• Responsive (sidebar burger sur mobile/tablette)
• Page d'accueil neutre : titre du dossier, stats, derniers fichiers modifiés, dossiers de premier niveau

Installation

Option 1 — Copier le dossier dans un projet

mon-projet/
├── ... (tes fichiers)
└── docboard/           ← colle ce dossier ici
    ├── server.py
    ├── dashboard.html
    ├── start-docboard.bat
    ├── start-docboard.sh
    └── README.md

Puis double-clic sur docboard/start-docboard.bat (Windows) ou docboard/start-docboard.sh (Mac/Linux). Par défaut, docboard sert le dossier parent du script — donc mon-projet/, exactement ce qu'on veut.

Option 2 — Le garder en dossier externe et lui pointer un projet

cd docboard/
./start-docboard.sh "/chemin/vers/mon-projet"

# ou sur Windows :
start-docboard.bat "D:\chemin\vers\mon-projet"

Pré-requis

Python 3.8+ uniquement (installé par défaut sur Mac et la plupart des Linux, à installer manuellement sur Windows via python.org en cochant « Add Python to PATH »).

Aucune dépendance pip. Tout le front-end utilise des CDN publics (jsdelivr).

Options CLI

python server.py [--root DIR] [--port N] [--host HOST] [--no-browser]

Option	Défaut	Description
--root	parent du script	Dossier à visualiser
--port	8765	Port HTTP (auto-incrémenté si déjà utilisé)
--host	127.0.0.1	Interface réseau d'écoute
--no-browser	désactivé	Empêcher l'ouverture automatique du navigateur

Personnalisation (optionnelle)

Créer un fichier docboard.config.json à la racine du projet visualisé (pas dans docboard/) pour personnaliser :

{
  "title": "Mon projet documentaire",
  "subtitle": "Notes, specs, documentation",
  "ignore_dirs": ["archives", "old"],
  "ignore_files": ["private.md"],
  "max_depth": 6
}

Tous les champs sont facultatifs. Par défaut :

• le titre = nom du dossier racine
• les dossiers techniques ignorés : .git, .venv, node_modules, __pycache__, dist, build, .cursor, .vscode, .idea, .next, .cache, docboard
• les fichiers cachés (commençant par .) sont ignorés

Architecture technique

 ┌───────────────────────────────┐
 │  navigateur (dashboard.html)  │   front statique, zéro backend-coupling
 └──────┬─────────────┬──────────┘
        │             │
        │ GET /__docboard__/api/tree     → arbo JSON auto-scannée
        │ GET /__docboard__/api/info     → nom + stats
        │ GET /__docboard__/api/recent   → derniers fichiers modifiés
        │ GET /<fichier-relatif>         → contenu brut (md/pdf/png/…)
        │
 ┌──────▼───────────────────────┐
 │  server.py  (stdlib seule)   │  scanne le dossier racine à la volée
 └──────────────────────────────┘

Le serveur est un ThreadingHTTPServer qui :

1. Expose les assets docboard/dashboard.html sous /__docboard__/static/
2. Sert les fichiers du projet racine à la racine URL (/mon-doc.md, /sous-dossier/fichier.pdf…)
3. Expose une petite API d'inspection sous /__docboard__/api/

Isolation : le serveur refuse tout accès en dehors du dossier racine (protection contre ..).

Raccourcis clavier

Touche	Action
Ctrl+K	Focus sur la recherche

Limitations

• Fichiers .docx, .xlsx, etc. : pas de prévisualisation (lien de téléchargement uniquement) — le navigateur n'en affiche pas nativement.
• Les CDN (marked, highlight.js) doivent être accessibles au premier chargement (ensuite le navigateur les met en cache). Pour un usage 100 % hors-ligne, on peut inliner ces scripts dans dashboard.html (~250 Ko).
• Seuls les .md sont indexés par la recherche plein-texte. Les PDFs ne sont pas extraits.

Licence

MIT — voir LICENSE.