Files

Julien Calixte ac00dab673 Chore/change theme (#13 )

* chore: script to change theme

* style: fix md

2025-08-01 10:48:53 +02:00

16 KiB

Raw Blame History

Plan d'Implémentation - Partage Public de Notes LiteNote

🎯 Vision de la Fonctionnalité

Permettre aux utilisateurs de LiteNote de partager publiquement certaines notes de leurs dépôts privés sans aucune infrastructure supplémentaire. Cette fonctionnalité utilise un système de "miroir public" intelligent qui synchronise automatiquement les notes marquées comme publiques vers un dépôt GitHub public dédié.

🏗️ Architecture Technique

Composants Principaux

Système de Métadonnées YAML : Utilise le frontmatter pour marquer les notes publiques
Dépôt Miroir Automatique : {username}-litenote-public créé automatiquement
Service de Synchronisation : Gestion intelligente des mises à jour
Processeur de Liens : Transformation des liens inter-notes
Gestionnaire d'Erreurs : Résolution automatique et manuelle des conflits

Flux de Fonctionnement

graph LR
    A[Note Privée] --> B[Métadonnées public: true]
    B --> C[Détection Automatique]
    C --> D[Traitement des Liens]
    D --> E[Synchronisation Miroir]
    E --> F[Note Publique Accessible]

📝 Système de Métadonnées

Format des Métadonnées Publiques

---
# Métadonnées de publication
public: true
public_title: "Mon Guide Public"
public_description: "Description visible publiquement"
public_tags: ["guide", "tutorial", "public"]
public_category: "documentation"

# Métadonnées de synchronisation
public_created: "2024-01-15T10:30:00Z"
public_updated: "2024-01-20T14:45:00Z"
public_version: 2

# Options de publication
public_show_backlinks: false
public_allow_comments: true
public_featured: false
---

# Contenu de la note...

Métadonnées Disponibles

Champ	Obligatoire	Description	Exemple
`public`	✅	Active le partage public	`true`
`public_title`	❌	Titre personnalisé pour le public	`"Mon Guide Complet"`
`public_description`	❌	Description visible publiquement	`"Un guide détaillé sur..."`
`public_tags`	❌	Tags pour organiser vos notes publiques	`["guide", "tutorial"]`
`public_category`	❌	Catégorie de la note	`"documentation"`
`public_show_backlinks`	❌	Afficher les liens entrants	`false`
`public_featured`	❌	Mettre en avant cette note	`true`

🗂️ Structure du Dépôt Miroir Public

{username}-litenote-public/
├── README.md                    # Page d'accueil générée
├── .litenote-mirror.json       # Configuration du miroir
├── .github/
│   └── workflows/
│       └── pages.yml           # Déploiement GitHub Pages (optionnel)
├── notes/
│   ├── index.md               # Index des notes publiques
│   ├── guides/
│   │   ├── guide-1.md
│   │   └── guide-2.md
│   └── articles/
│       └── article-1.md
├── assets/
│   ├── images/
│   └── files/
└── _data/
    ├── notes-index.json       # Index searchable
    └── tags.json             # Index des tags

Configuration du Miroir (.litenote-mirror.json)

{
  "version": "1.0",
  "source_repo": "username/private-notes",
  "created": "2024-01-15T10:30:00Z",
  "last_sync": "2024-01-20T14:45:00Z",
  "sync_count": 42,
  "settings": {
    "auto_generate_index": true,
    "preserve_folder_structure": true,
    "copy_assets": true,
    "generate_rss": false
  },
  "stats": {
    "total_notes": 15,
    "total_assets": 8,
    "total_tags": 12
  }
}

🔄 Service de Synchronisation

Architecture du Service

interface MirrorSyncService {
  // Gestion du dépôt miroir
  createMirrorRepo(username: string): Promise<string>
  getMirrorRepoName(username: string): string
  checkMirrorExists(username: string): Promise<boolean>
  
  // Synchronisation des notes
  syncNote(note: PublicNote): Promise<SyncResult>
  syncAllPublicNotes(): Promise<SyncResult[]>
  removeNoteFromMirror(notePath: string): Promise<boolean>
  
  // Gestion des assets
  syncAssets(assets: string[]): Promise<string[]>
  updateAssetReferences(content: string, assetMap: Map<string, string>): string
  
  // Utilitaires
  generateMirrorIndex(): Promise<void>
  updateMirrorConfig(): Promise<void>
}

Flux de Synchronisation

graph TD
    A[Note modifiée] --> B[Détection changement]
    B --> C{Note publique?}
    C -->|Non| D[Vérifier si était publique]
    C -->|Oui| E[Extraire métadonnées]
    D -->|Était publique| F[Supprimer du miroir]
    D -->|N'était pas publique| G[Aucune action]
    E --> H[Analyser assets référencés]
    H --> I[Préparer contenu pour miroir]
    I --> J{Dépôt miroir existe?}
    J -->|Non| K[Créer dépôt miroir]
    J -->|Oui| L[Synchroniser assets]
    K --> L
    L --> M[Commit note vers miroir]
    M --> N[Mettre à jour index]
    N --> O[Notification utilisateur]
    F --> P[Mettre à jour index]
    P --> O

🔗 Gestion des Liens Inter-Notes

Problématique des Liens

Dans LiteNote, les utilisateurs utilisent la syntaxe [[nom-de-note]] pour créer des liens entre notes. Quand une note devient publique, ces liens peuvent pointer vers :

Notes publiques → Doivent être transformés en liens fonctionnels
Notes privées → Doivent être gérés avec avertissement
Notes inexistantes → Doivent être préservés comme liens brisés

Algorithme de Transformation

graph TD
    A[Contenu avec liens [[note]]] --> B[Extraire tous les liens]
    B --> C[Pour chaque lien]
    C --> D{Note existe?}
    D -->|Non| E[Marquer comme lien brisé]
    D -->|Oui| F{Note est publique?}
    F -->|Oui| G[Transformer en lien relatif]
    F -->|Non| H[Transformer en lien désactivé]
    G --> I[Ajouter à la liste des liens publics]
    H --> J[Ajouter à la liste des liens privés]
    E --> K[Ajouter à la liste des liens brisés]
    I --> L[Générer contenu final]
    J --> L
    K --> L

Transformation des Liens

<!-- Dans la note privée -->
Voir aussi [[ma-note-privee]] et [[ma-note-publique]]

<!-- Dans la note publique -->
Voir aussi [ma-note-privee](# "Cette note n'est pas publique") et [ma-note-publique](./ma-note-publique.md)

🎛️ Interface Utilisateur

Indicateurs Visuels

Dans la liste des notes :

🌐 Icône pour les notes publiques
📝 Icône pour les notes privées
⏳ Icône pour les notes en cours de synchronisation

Dans l'éditeur de note :

Badge "PUBLIC" dans l'en-tête
Lien vers la version publique
Statut de synchronisation

Dashboard des Notes Publiques

<!-- Composant PublicNotesDashboard.vue -->
<template>
  <div class="public-dashboard">
    <div class="dashboard-header">
      <h2>Mes Notes Publiques</h2>
      <div class="mirror-info">
        <span>Dépôt miroir : </span>
        <a :href="mirrorRepoUrl" target="_blank">
          {{ mirrorRepoName }}
        </a>
      </div>
    </div>
    
    <div class="public-notes-list">
      <div 
        v-for="note in publicNotes" 
        :key="note.sha"
        class="public-note-item"
      >
        <div class="note-info">
          <h3>{{ note.metadata.public_title || note.title }}</h3>
          <p>{{ note.metadata.public_description }}</p>
          <div class="note-tags">
            <span 
              v-for="tag in note.metadata.public_tags"
              :key="tag"
              class="tag"
            >
              {{ tag }}
            </span>
          </div>
        </div>
        
        <div class="note-actions">
          <button @click="editNote(note)">Éditer</button>
          <button @click="viewPublic(note)">Voir public</button>
          <button @click="unpublish(note)">Dépublier</button>
        </div>
        
        <div class="sync-status">
          <span :class="getSyncStatusClass(note)">
            {{ getSyncStatusText(note) }}
          </span>
        </div>
      </div>
    </div>
  </div>
</template>

⚠️ Gestion des Erreurs et Conflits

Types d'Erreurs

Erreurs de Création du Dépôt Miroir
- Nom de dépôt déjà pris → Proposition de noms alternatifs
- Permissions insuffisantes → Guide pour configurer les permissions GitHub
- Quota GitHub dépassé → Information sur les limites et solutions
Erreurs de Synchronisation
- Conflits de contenu → Résolution automatique ou manuelle
- Fichiers trop volumineux → Compression ou exclusion automatique
- Rate limiting GitHub → Queue avec retry automatique
Erreurs de Réseau
- Perte de connexion → Mise en queue pour synchronisation ultérieure
- Timeout API → Retry avec backoff exponentiel
- Authentification expirée → Refresh automatique du token

Interface de Résolution des Conflits

<!-- ConflictResolutionModal.vue -->
<template>
  <div class="conflict-modal" v-if="conflict">
    <div class="modal-content">
      <div class="modal-header">
        <h2>🔄 Conflit de Synchronisation</h2>
        <p>{{ conflict.description }}</p>
      </div>
      
      <div class="conflict-details">
        <div class="version-comparison">
          <div class="version local">
            <h3>Version Locale</h3>
            <div class="content-preview">{{ conflict.localContent }}</div>
          </div>
          
          <div class="version remote">
            <h3>Version Miroir</h3>
            <div class="content-preview">{{ conflict.remoteContent }}</div>
          </div>
        </div>
      </div>
      
      <div class="resolution-actions">
        <button @click="acceptAutoMerge">Accepter la fusion automatique</button>
        <button @click="useLocalVersion">Utiliser la version locale</button>
        <button @click="useRemoteVersion">Utiliser la version du miroir</button>
        <button @click="editManually">Éditer manuellement</button>
        <button @click="skipSync">Ignorer cette synchronisation</button>
      </div>
    </div>
  </div>
</template>

🌐 URLs Publiques

Vos notes publiques sont accessibles via :

Format principal :
https://litenote.space/{username}/{username}-litenote-public

Note spécifique :
https://litenote.space/{username}/{username}-litenote-public?note=notes/ma-note.md

Avec GitHub Pages (optionnel) :
https://{username}.github.io/{username}-litenote-public/

🔒 Sécurité et Confidentialité

Ce qui est Partagé

✅ Contenu des notes marquées public: true
✅ Assets référencés (images, fichiers) dans ces notes
✅ Métadonnées publiques définies par vous

Ce qui Reste Privé

❌ Toutes les autres notes de votre dépôt privé
❌ Historique des commits du dépôt privé
❌ Métadonnées privées (dates de création, etc.)
❌ Structure complète de votre dépôt privé