184 lines
6.5 KiB
Markdown
184 lines
6.5 KiB
Markdown
# 🌌 ObsiViewer — Explorateur de voûte Obsidian
|
||
|
||
ObsiViewer est une application **Angular 20** qui permet de parcourir une voûte Obsidian en lecture seule : navigation dans l’arborescence des notes, rendu Markdown enrichi, visualisation du graphe et filtrage avancé par tags ou dates.
|
||
|
||
> 📝 **Mode démo par défaut** : l’interface repose sur des données générées par `VaultService`. Vous pouvez connecter ObsiViewer à vos fichiers Markdown via le serveur Express fourni.
|
||
|
||
---
|
||
|
||
## 🚀 Aperçu rapide
|
||
|
||
- **Framework** : Angular + TailwindCSS
|
||
- **Rendu Markdown** : `MarkdownService` (supporte Mermaid, KaTeX, surlignage de code)
|
||
- **Visualisations** :
|
||
- Explorateur de fichiers (`app/components/file-explorer/`)
|
||
- Graphe de liens (`app/components/graph-view/`)
|
||
- Vue tags (`app/components/tags-view/`)
|
||
- Recherche + calendrier (intégré à `app.component.simple.html`)
|
||
- **Backend optionnel** : serveur Express (`server/index.mjs`) qui lit la voûte physique (`vault/`) et expose une API REST.
|
||
|
||
---
|
||
|
||
## 🧰 Prérequis
|
||
|
||
- Node.js **20+** et npm (`node --version`)
|
||
- Angular CLI (facultatif mais pratique) : `npm install -g @angular/cli`
|
||
- Docker (facultatif) pour utiliser les scripts situés dans `docker/` et `docker-compose/`
|
||
|
||
---
|
||
|
||
## ⚙️ Installation & scripts utiles
|
||
|
||
```bash
|
||
npm install # Installe toutes les dépendances
|
||
npm run dev # Lance l'app en mode développement (http://localhost:3000)
|
||
npm run build # Compile la version production dans dist/
|
||
npm run preview # Sert la build de prod avec ng serve
|
||
```
|
||
|
||
👉 Le port de dev et la configuration de build sont définis dans `angular.json`.
|
||
|
||
---
|
||
|
||
## 🗂️ Structure du dépôt
|
||
|
||
- `src/` : composant principal `app.component.ts`, vue simplifiée, composants UI, services, types
|
||
- `server/` : serveur Express pour charger vos notes locales et fournir l’API `/api`
|
||
- `vault/` : emplacement attendu des fichiers Markdown (créé au démarrage du serveur)
|
||
- `docker/` & `docker-compose/` : scripts et configurations pour l’exécution en conteneurs
|
||
- `index.tsx` : point d’entrée Angular (bootstrap sans zone)
|
||
- `metadata.json` : métadonnées pour l’intégration AI Studio
|
||
|
||
---
|
||
|
||
## 🔌 Configurer l’API locale (optionnel)
|
||
```bash
|
||
npm run build # génère dist/
|
||
node server/index.mjs # lance l'API + serveur statique sur http://localhost:4000
|
||
```
|
||
Assurez-vous que vos notes Markdown se trouvent dans `vault/`. L'API expose :
|
||
|
||
- `GET /api/health`
|
||
- `GET /api/vault`
|
||
- `GET /api/vault/bookmarks` - Récupère les favoris depuis `<vault>/.obsidian/bookmarks.json`
|
||
- `PUT /api/vault/bookmarks` - Sauvegarde les favoris (avec gestion de conflits via `If-Match`)
|
||
- `GET /api/files/metadata`
|
||
- `GET /api/files/by-date?date=2025-01-01`
|
||
- `GET /api/files/by-date-range?start=...&end=...`
|
||
|
||
---
|
||
|
||
## ⭐ Gestion des favoris (Bookmarks)
|
||
|
||
ObsiViewer implémente une **gestion complète des favoris** 100% compatible avec Obsidian, utilisant `<vault>/.obsidian/bookmarks.json` comme source unique de vérité.
|
||
|
||
### Fonctionnalités
|
||
|
||
- **Synchronisation bidirectionnelle** : Les modifications dans ObsiViewer apparaissent dans Obsidian et vice-versa
|
||
- **Deux modes d'accès** :
|
||
- **File System Access API** (préféré) : Sélectionnez votre dossier vault directement depuis le navigateur
|
||
- **Serveur Bridge** : L'API Express lit/écrit le fichier `.obsidian/bookmarks.json`
|
||
- **Opérations complètes** : Créer, modifier, supprimer, réorganiser, grouper
|
||
- **Import/Export** : Importer ou exporter vos favoris au format JSON Obsidian
|
||
- **Détection de conflits** : Alerte si le fichier a été modifié en externe avec options de résolution
|
||
- **Sauvegarde automatique** : Debouncing de 800ms pour éviter les écritures excessives
|
||
- **Interface responsive** : Optimisée pour desktop et mobile avec thèmes clair/sombre
|
||
|
||
### Comment utiliser
|
||
|
||
#### Mode Navigateur (File System Access API)
|
||
|
||
1. Cliquez sur **"Connect Vault"** dans le panneau Favoris
|
||
2. Sélectionnez le dossier racine de votre vault Obsidian
|
||
3. Accordez les permissions de lecture/écriture
|
||
4. ObsiViewer accède directement à `.obsidian/bookmarks.json`
|
||
|
||
> ⚠️ Nécessite Chrome 86+, Edge 86+, ou Opera 72+ (pas de support Firefox/Safari)
|
||
|
||
#### Mode Serveur
|
||
|
||
```bash
|
||
node server/index.mjs
|
||
```
|
||
|
||
Le serveur lit/écrit automatiquement `vault/.obsidian/bookmarks.json`.
|
||
|
||
### Structure des données
|
||
|
||
Format JSON compatible Obsidian :
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"type": "group",
|
||
"ctime": 1704067200000,
|
||
"title": "Mes Notes",
|
||
"items": [
|
||
{
|
||
"type": "file",
|
||
"ctime": 1704067201000,
|
||
"path": "Notes/important.md",
|
||
"title": "Note Importante"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Types supportés : `group`, `file` (dossiers, recherches, headings, blocks parsés mais non affichés).
|
||
|
||
### Architecture technique
|
||
|
||
```
|
||
src/core/bookmarks/
|
||
├── types.ts # Types TypeScript
|
||
├── bookmarks.utils.ts # Opérations arbre + validation
|
||
├── bookmarks.repository.ts # Adapters de persistance
|
||
└── bookmarks.service.ts # Service Angular avec Signals
|
||
|
||
src/components/
|
||
├── bookmarks-panel/ # Composant principal
|
||
└── bookmark-item/ # Item d'arborescence
|
||
```
|
||
|
||
Le service utilise les **Signals Angular** pour la réactivité et implémente un système de sauvegarde automatique avec debounce.
|
||
|
||
---
|
||
|
||
## 🐳 Exécution avec Docker (facultatif)
|
||
|
||
- `docker/build-img.ps1` / `docker/deploy-img.ps1` pour construire et pousser une image locale
|
||
- `docker/Dockerfile.origi` pour une build manuelle (`docker build ...`)
|
||
- `docker-compose/docker-compose.yml` pour orchestrer un conteneur préconfiguré
|
||
|
||
💡 Pensez à personnaliser les fichiers `.env` (`.env.local`, `docker-compose/.env`) avant toute utilisation réelle.
|
||
|
||
---
|
||
|
||
## 🧪 Tests & qualité
|
||
|
||
- Aucun test automatisé n’est fourni pour l’instant.
|
||
- Ajoutez vos propres suites (`ng test`, `ng e2e`) selon vos besoins.
|
||
|
||
---
|
||
|
||
## ⚠️ Points d’attention
|
||
|
||
- Les scripts Docker hérités supposent la présence d’un dossier `server/` et d’un schéma `db/schema.sql` (non inclus ici).
|
||
- Les secrets fournis en exemple dans les fichiers `.env` doivent être remplacés avant toute utilisation en production.
|
||
- Le rendu Markdown peut nécessiter des adaptations pour des voûtes Obsidian complexes.
|
||
|
||
---
|
||
|
||
## 📚 Ressources
|
||
|
||
- Angular : <https://angular.dev/>
|
||
- CLI Angular (`ng serve`) : <https://angular.dev/cli/serve>
|
||
- Guide Docker Compose : voir `docker-compose/README.md`
|
||
|
||
---
|
||
|
||
✨ Bonne exploration dans ObsiViewer !
|