ObsiViewer est une application web Angular 20 moderne et performante qui permet d'explorer et visualiser une voûte Obsidian en lecture seule. Conçue comme une alternative légère pour consulter vos notes Markdown depuis n'importe quel navigateur, elle offre une expérience riche avec navigation fluide, rendu Markdown avancé, visualisation interactive du graphe de connaissances et recherche compatible Obsidian.

Cas d'usage principaux

📖 Consultation de votre vault Obsidian depuis un navigateur
🌐 Partage de vos notes en lecture seule (hébergement web)
📱 Accès mobile optimisé à votre base de connaissances
🔍 Exploration visuelle des liens entre vos notes
📊 Analyse du vault via graphe et statistiques

📝 Mode démo par défaut : l'interface fonctionne avec des données générées par VaultService. Connectez-la à vos fichiers Markdown réels via le serveur Express pour une utilisation complète.

✨ Fonctionnalités Principales

Explorateur de fichiers : Arborescence complète avec dossiers pliables/dépliables
Recherche avancée : Moteur de recherche compatible Obsidian avec opérateurs (path:, tag:, line:, etc.)
Vue Tags : Visualisation et filtrage par tags avec compteurs
Calendrier : Navigation temporelle par dates de création/modification
Favoris (Bookmarks) : Gestion complète compatible avec .obsidian/bookmarks.json
Breadcrumbs : Navigation contextuelle avec fil d'Ariane

📝 Rendu Markdown

Markdown enrichi : Support complet de la syntaxe Obsidian
Wikilinks : [[liens internes]] avec preview au survol et navigation
Callouts : Blocs d'information stylisés (note, warning, info, etc.)
Syntax highlighting : Coloration syntaxique pour 100+ langages via highlight.js
Diagrammes Mermaid : Rendu des diagrammes et flowcharts
Mathématiques : Support LaTeX/KaTeX pour formules mathématiques
Tables avancées : Multi-markdown tables avec fusion de cellules
Task lists : Listes de tâches interactives
Footnotes : Notes de bas de page
Embeddings : Images et attachements avec résolution intelligente

🕸️ Graphe de Connaissances

Visualisation interactive : Graphe de liens basé sur d3-force
Physique réaliste : Simulation de forces pour placement optimal
Drag & Drop : Déplacement et fixation des nœuds
Filtres avancés : Tags, attachments, orphelins, recherche
Color Groups : Coloration personnalisée par requêtes
Paramètres complets : 14+ options (forces, apparence, affichage)
Persistance : Sauvegarde dans .obsidian/graph.json
Mode focus : Centré sur une note avec profondeur configurable

🔍 Recherche et Filtrage

Moteur de recherche Obsidian-compatible avec tous les opérateurs
Assistant de requêtes : Autocomplétion intelligente avec suggestions
Historique : Mémorisation des 10 dernières recherches par contexte
Highlighting : Mise en évidence des résultats
Tri multiple : Pertinence, nom, date de modification
Preview : Extraits contextuels dans les résultats

🎨 Interface Utilisateur

Design moderne : Interface soignée inspirée d'Obsidian
Dark/Light mode : Thèmes clair et sombre avec transition fluide
Responsive : Optimisé desktop, tablette et mobile
Sidebar redimensionnable : Ajustement de la largeur des panneaux
Keyboard shortcuts : Raccourcis clavier (Alt+R, Alt+D)
Animations fluides : 60fps avec optimisations performance

🧰 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

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.

🏗️ Architecture

Stack Technique

Technologie	Version	Usage
Angular	20.3.x	Framework (Signals, Standalone Components)
TypeScript	5.8.x	Langage (mode strict)
TailwindCSS	3.4.x	Styling et design system
Angular CDK	20.2.x	Overlay, drag-drop
RxJS	7.8.x	Programmation réactive
Express	5.1.x	API REST backend
Chokidar	4.0.x	File watching
Markdown-it	14.1.x	Parsing/rendu Markdown
highlight.js	11.10.x	Syntax highlighting
mermaid	11.12.x	Diagrammes
d3-force	3.0.x	Physique du graphe
date-fns	4.1.x	Dates

Patterns

Signals pour la réactivité fine-grained
Standalone Components (sans NgModules)
Repository Pattern (FileSystem / Server / Mémoire)
Services pour la logique métier
Change Detection OnPush
Bootstrap sans Zone.js

Structure du Projet

ObsiViewer/
├── src/
│   ├── app/
│   │   ├── core/                 # Services core (download, theme)
│   │   └── graph/                # Graph settings & runtime
│   ├── components/               # UI (bookmarks, graph, search, calendar, etc.)
│   ├── core/                     # bookmarks/, graph/, search/, services/
│   ├── services/                 # vault.service, markdown.service, etc.
│   ├── shared/                   # Overlays, composants communs
│   ├── styles/                   # CSS globaux, tokens
│   ├── types/                    # Types TS
│   └── app.component.ts          # Composant racine
├── server/index.mjs              # API Express + fichiers statiques
├── docker*/                      # Docker & Compose
├── docs/                         # Documentation détaillée
├── vault/                        # Voûte Obsidian (créée au démarrage)
├── index.tsx                     # Bootstrap Angular
├── angular.json, tsconfig.json   # Configs
└── package.json                  # Dépendances

🔌 Configurer l’API locale (optionnel)

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 :

Endpoints Principaux

Méthode	Endpoint	Description
GET	`/api/health`	État du serveur
GET	`/api/vault`	Liste complète des notes avec contenu
GET	`/api/vault/events`	Server-Sent Events pour live reload
GET	`/api/files/metadata`	Métadonnées de tous les fichiers
GET	`/api/files/by-date`	Fichiers créés/modifiés à une date
GET	`/api/files/by-date-range`	Fichiers dans un intervalle
GET	`/api/vault/bookmarks`	Favoris `.obsidian/bookmarks.json`
PUT	`/api/vault/bookmarks`	Sauvegarde favoris (avec If-Match)
GET	`/api/vault/graph`	Configuration graphe `.obsidian/graph.json`
PUT	`/api/vault/graph`	Sauvegarde configuration graphe
GET	`/api/attachments/resolve`	Résolution intelligente d'attachements

Fonctionnalités Serveur

Live Reload : Détection des changements de fichiers via Chokidar
Server-Sent Events : Notifications en temps réel des modifications
Résolution d'attachements : Recherche intelligente dans l'arborescence
Atomic Writes : Écritures sécurisées avec fichiers temporaires
Conflict Detection : Gestion des conflits avec hash de révision
CORS Safe : Configuration proxy pour développement

⭐ 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)

Cliquez sur "Connect Vault" dans le panneau Favoris
Sélectionnez le dossier racine de votre vault Obsidian
Accordez les permissions de lecture/écriture
ObsiViewer accède directement à .obsidian/bookmarks.json

⚠️ Nécessite Chrome 86+, Edge 86+, ou Opera 72+ (pas de support Firefox/Safari)

Mode Serveur

node server/index.mjs

Le serveur lit/écrit automatiquement vault/.obsidian/bookmarks.json.

Structure des données

Format JSON compatible Obsidian :

{
  "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

Tests unitaires

Scripts disponibles:

npm run test:markdown  # src/services/markdown.service.spec.ts
# Ou exécuter un test spécifique (exemples):
node --loader ts-node/esm --test src/services/wikilink-parser.service.spec.ts
node --loader ts-node/esm --test src/core/bookmarks/bookmarks.service.spec.ts
node --loader ts-node/esm --test src/core/bookmarks/bookmarks.utils.spec.ts
node --loader ts-node/esm --test src/core/search/search-parser.spec.ts

Tests manuels recommandés

Wikilinks: [[note]], [[note|Alias]], [[note#Section]], [[note#^block]] → navigation + preview au survol.
Graph View: drag & drop, options (forces, affichage), groupes colorés, filtres (tags/attachments/orphans).
Bookmarks: connexion vault, création/édition/suppression, drag & drop, import/export, détection de conflits.
Recherche: opérateurs path:, file:, tag:, line:, section:, [property], OR/NOT/()``, exact phrases, wildcard, regex.

🛠️ Développement

Standards de code

TypeScript strict, architecture Angular 20 (Standalone + Signals)
ChangeDetection OnPush, composantisation claire
TailwindCSS (dark mode via classe dark/[data-theme="dark"])

Conventions

Composants: kebab-case.component.ts, Services: kebab-case.service.ts
Types/Interfaces: PascalCase, constantes: SCREAMING_SNAKE_CASE

Variables d’environnement

Variable	Description	Défaut
`PORT`	Port du serveur Express	`4000`
`NODE_ENV`	Environnement	`development`
`VAULT_PATH`	Chemin du vault (optionnel)	`./vault`

Contribution

Fork → branche feature/x
Commits conventionnels (feat:, fix:, docs:...)
PR avec description claire + captures si UI

🔐 Sécurité

Lecture seule des notes (écriture uniquement sur .obsidian/bookmarks.json et .obsidian/graph.json)
Pas d’authentification intégrée (prévoir un reverse proxy/SSO en production)
Résolution d’attachements sécurisée (vérifications d’existence)
Échappement du HTML pour réduire les risques XSS via Markdown
Ne pas committer de secrets .env

📈 Performance

Wikilinks: ~30ms/100 liens (voir IMPLEMENTATION_SUMMARY.md)
Graph 1000 nœuds: ~400ms initial, 60fps animation
Recherche complexe 2000+ notes: <200ms (voir SEARCH_COMPLETE.md)
Optimisations: Signals, OnPush, LRU cache (previews), debounce (250–800ms), rAF, zoneless bootstrap

🐛 Problèmes connus

File System Access API non supportée sur Firefox/Safari → utiliser le mode serveur Express
Zoom/Pan du graphe non implémenté (prévu via d3-zoom)
bookmark-item: édition inline TODO (voir commentaire dans le code)
Contexte menu z-index (UI) à ajuster dans SCSS
Très grands vaults (>5000 notes): envisager filtrage/virtualisation

⚠️ 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.

📝 Changelog

Voir les fichiers de documentation pour historiques détaillés :

IMPLEMENTATION_SUMMARY.md - Wikilinks & Graph View
SEARCH_COMPLETE.md - Système de recherche
docs/BOOKMARKS_CHANGELOG.md - Évolution des favoris
GRAPH_VIEW_SEARCH_IMPLEMENTATION.md - Graph & Search Assistant

Version Actuelle : 0.0.0 (Développement)

Fonctionnalités majeures :

✅ Navigation complète vault Obsidian
✅ Rendu Markdown enrichi avec wikilinks
✅ Graph View interactif avec parité Obsidian
✅ Système de recherche avancée
✅ Gestion bookmarks synchronisée
✅ Live reload avec SSE
✅ Dark/Light mode
✅ Responsive mobile

📄 Licence

Pas de licence spécifiée - Usage libre pour développement et consultation.

⚠️ Note : Ajoutez une licence appropriée (MIT, Apache 2.0, GPL, etc.) avant publication ou distribution.

👥 Auteurs et Contributeurs

Développement principal : Projet développé avec assistance AI (Claude/Anthropic)

Technologies et Inspirations :

Obsidian - Inspiration design et fonctionnalités
Angular - Framework
TailwindCSS - Styling
D3.js - Visualisation graphe

🔗 Liens Utiles

Documentation Projet

Architecture Complète - Documentation technique détaillée
Guide Bookmarks - Système de favoris
Guide Wikilinks - Liens internes
Guide Recherche - Moteur de recherche
Guide Graph - Configuration graphe

Resources Externes

API Documentation

File System Access API : MDN Web Docs
Server-Sent Events : MDN Web Docs

🎯 Quick Start Complet

# 1. Installation
git clone <repo-url>
cd ObsiViewer
npm install

# 2. Démarrage développement (mode demo)
npm run dev
# → Ouvrir http://localhost:3000

# 3. Avec votre vault (mode serveur)
mkdir -p vault
# Copier vos notes .md dans vault/
npm run build
node server/index.mjs
# → Ouvrir http://localhost:4000

# 4. Production
npm run build
# Déployer le contenu de dist/ sur votre hébergement

✨ Bonne exploration dans ObsiViewer ! ✨

💡 Besoin d'aide ? Consultez la documentation dans /docs ou ouvrez une issue.

🚀 Prêt pour la production ? Voir ROADMAP.md pour les prochaines étapes.

Languages

TypeScript 72.9%

HTML 16%

CSS 4.3%

JavaScript 3.2%

SCSS 1.8%

Other 1.8%

README.md Unescape Escape

🌌 ObsiViewer — Explorateur de voûte Obsidian

📋 Description