ObsiViewer/docs/QUICK_START_GRAPH_SEARCH.md

Guide de Démarrage Rapide - Graph View & Search Assistant

🚀 Lancement

# Installation des dépendances (si nécessaire)
npm install

# Démarrage du serveur de développement
npm start

# L'application sera accessible sur http://localhost:4000

📍 Accès aux Fonctionnalités

1. Assistant de Recherche (3 emplacements)

A. Barre Latérale (Vue Mobile/Desktop)

1. Cliquer sur l'icône de recherche dans la navigation
2. Le champ de recherche avec assistant apparaît
3. Focus → popover s'ouvre automatiquement

B. Header Central (Vue Desktop)

1. Barre de recherche toujours visible en haut
2. Focus → popover s'ouvre avec suggestions

C. Graph Settings → Filters

1. Ouvrir Graph View (icône graphe)
2. Panel "Graph settings" à droite
3. Section "Filters" → champ "Search files..."

2. Graph View avec Filtres

Accès:

1. Cliquer sur l'icône Graph View (4ème icône navigation)
2. Panel "Graph settings" s'ouvre à droite

Filtres disponibles:

• ☑️ Tags: Afficher les nœuds de tags (#code, #todo, etc.)
• ☑️ Attachments: Afficher fichiers PDF, PNG, etc.
• ☑️ Existing files only: Masquer les liens non résolus
• ☑️ Orphans: Afficher les nœuds sans connexions

Recherche avancée:

• Taper dans "Search files..." pour filtrer par requête Obsidian

3. Groups (Colorisation)

Créer un groupe:

1. Graph View → Section "Groups"
2. Cliquer "New group"
3. Éditer la requête (ex: tag:#code, file:test, path:folder/)
4. Le groupe colore automatiquement les nœuds matchant

Gérer les groupes:

• Modifier: Éditer directement la requête dans l'input
• Supprimer: Cliquer l'icône ❌
• Réorganiser: L'ordre détermine la priorité (haut = prioritaire)

🔍 Syntaxe de Recherche Obsidian

Préfixes Supportés

Préfixe	Description	Exemple
path:	Chemin du fichier	path:folder/subfolder/
file:	Nom du fichier	file:readme
tag:	Tag Obsidian	tag:#todo ou tag:#code
line:	Mots sur la même ligne	line:important deadline
section:	Sous le même heading	section:Introduction
[property]	Propriété YAML	[title:test] ou [author]

Opérateurs

Opérateur	Description	Exemple
OR	Union (l'un OU l'autre)	tag:#todo OR tag:#urgent
AND	Intersection (implicite)	tag:#code file:test
-	Exclusion (NOT)	-tag:#done
"..."	Phrase exacte	"exact phrase"
*	Wildcard	test* ou *ing
()	Groupes	(tag:#a OR tag:#b) file:test

Exemples de Requêtes

# Fichiers avec tag #code
tag:#code

# Fichiers dans le dossier "docs"
path:docs/

# Fichiers contenant "TODO" mais pas "DONE"
TODO -DONE

# Tags #todo OU #urgent dans le dossier "projects"
(tag:#todo OR tag:#urgent) path:projects/

# Fichiers avec propriété YAML "author: John"
[author:John]

# Phrase exacte
"fonction principale"

# Wildcard sur nom de fichier
file:test*

📚 Utilisation de l'Assistant

Options de Recherche (Cliquables)

Au focus dans un champ de recherche, le popover affiche:

┌─────────────────────────────────────┐
│ Search options              ⓘ Help │
├─────────────────────────────────────┤
│ path:    match path of the file     │
│ file:    match file name            │
│ tag:     search for tags            │
│ line:    search keywords on line    │
│ section: search under same heading  │
│ [property] match property           │
└─────────────────────────────────────┘

Cliquer une option → insère le préfixe dans l'input

Suggestions Dynamiques

Taper path: → Liste des dossiers:

┌─────────────────────────┐
│ attachments             │
│ folder                  │
│ deep                    │
│ deep/path               │
│ tata/briana             │
└─────────────────────────┘

Taper tag: → Liste des tags:

┌─────────────────────────┐
│ #code                   │
│ #todo                   │
│ #markdown               │
│ #test                   │
└─────────────────────────┘

Taper file: → Liste des fichiers:

┌─────────────────────────┐
│ README.md               │
│ test.md                 │
│ welcome.md              │
└─────────────────────────┘

Historique

Après avoir soumis des requêtes, l'historique apparaît:

┌─────────────────────────────────────┐
│ History              Clear history  │
├─────────────────────────────────────┤
│ tag:#code OR tag:#test              │
│ path:docs/                          │
│ file:readme                         │
│ [description:page]                  │
└─────────────────────────────────────┘

• Cliquer un item → applique la requête
• Clear history → vide l'historique (localStorage)
• Maximum: 10 requêtes récentes

Navigation Clavier

• ↓ : Sélectionner suggestion suivante
• ↑ : Sélectionner suggestion précédente
• Enter : Appliquer suggestion sélectionnée
• Esc : Fermer le popover

🎨 Colorisation avec Groups

Exemple: Colorer tous les fichiers de test en rose

1. Graph View → "Groups" → "New group"
2. Query: file:test
3. Le groupe applique automatiquement la couleur rose aux fichiers contenant "test"

Exemple: Colorer par tags

Groupe 1 (violet): tag:#code
Groupe 2 (bleu):   tag:#documentation
Groupe 3 (vert):   tag:#todo

Priorité: Si un fichier a #code ET #todo, il sera violet (groupe 1 prioritaire)

Exemple: Colorer par dossier

Groupe 1 (rouge):  path:important/
Groupe 2 (jaune):  path:drafts/
Groupe 3 (gris):   path:archive/

🔧 Configuration Persistée

Fichier .obsidian/graph.json

Tous les réglages sont sauvegardés automatiquement:

{
  "search": "tag:#code",
  "showTags": true,
  "showAttachments": true,
  "hideUnresolved": true,
  "showOrphans": true,
  "colorGroups": [
    {
      "query": "file:test",
      "color": {
        "a": 1,
        "rgb": 14701188
      }
    }
  ],
  "showArrow": true,
  "textFadeMultiplier": -1.7,
  "nodeSizeMultiplier": 1,
  "lineSizeMultiplier": 1,
  "centerStrength": 0.518713248970312,
  "repelStrength": 10,
  "linkStrength": 0.690311418685121,
  "linkDistance": 102
}

• Debounce: 250ms après modification
• Polling: Détection changements externes toutes les 2s
• Atomic writes: .tmp + rename pour éviter corruption

localStorage

Historiques de recherche stockés par contexte:

obsidian-search-history-vault-sidebar  → Sidebar mobile
obsidian-search-history-vault-header   → Header desktop
obsidian-search-history-graph          → Graph filters

🐛 Dépannage

Le popover ne s'ouvre pas

• Vérifier que le focus est bien dans l'input
• Console browser → chercher erreurs JavaScript

Les suggestions sont vides

• Vérifier que le vault contient des fichiers/tags
• L'index se rebuild au chargement des notes
• Console → vérifier GraphIndexService.rebuildIndex appelé

Les filtres ne s'appliquent pas

• Vérifier .obsidian/graph.json existe et est valide JSON
• Recharger la page pour forcer rechargement config
• Tester avec config minimale

Les couleurs de groupe ne s'appliquent pas

• Vérifier syntaxe de la requête (utiliser l'assistant)
• Tester requête dans "Search files..." d'abord
• Vérifier ordre des groupes (priorité haut → bas)

📊 Vérification de Parité

Checklist Image 1 vs ObsiViewer

• Même nombre de nœuds visibles
• Tags affichés comme nœuds (#code, #markdown, etc.)
• Attachments visibles (PDF, PNG)
• Liens vers fichiers non résolus masqués (si "Existing files only")
• Orphans affichés/masqués selon toggle
• Groupe rose appliqué aux fichiers matchant file:test
• Flèches sur les arêtes (si "Arrows" activé)

🎯 Cas d'Usage Courants

1. Trouver tous les TODOs urgents

tag:#todo tag:#urgent -tag:#done

2. Documentation projet spécifique

path:docs/project-x/ file:*.md

3. Fichiers récents avec keyword

"important meeting" [date:2024-10]

4. Code non testé

path:src/ -file:*test* -file:*spec*

5. Groupe de couleurs par statut

Groupe 1 (vert):  tag:#done
Groupe 2 (jaune): tag:#in-progress
Groupe 3 (rouge): tag:#blocked

📖 Ressources

• Documentation complète: GRAPH_VIEW_SEARCH_IMPLEMENTATION.md
• Tests: src/core/search/search-parser.spec.ts
• Obsidian Search Docs: https://help.obsidian.md/Plugins/Search

---

Bon usage! 🎉