Annotations
Les annotations permettent à vos relecteurs de commenter des passages précis de vos documents Markdown. Elles sont disponibles en mode revue (toujours activées) et en mode hybride (activées par document via le front matter).
Principe
Un relecteur accède au document via son lien de partage, sélectionne un passage de texte et ajoute un commentaire. Le passage annoté est surligné dans le document avec la couleur du relecteur. Les autres relecteurs peuvent voir toutes les annotations et y répondre.
Aucune inscription n'est requise : chaque relecteur choisit un pseudonyme lors de sa première annotation. Ce pseudonyme est mémorisé dans le navigateur (localStorage).
Créer une annotation
- Ouvrez le document via son lien de partage
- Sélectionnez un passage de texte dans le document
- Un bouton d'annotation apparaît
- Saisissez votre pseudonyme si c'est votre première visite
- Rédigez votre commentaire
- Validez
Le passage annoté est immédiatement surligné dans le document. Chaque relecteur se voit attribuer une couleur distincte parmi une palette de 12 couleurs.
Consulter les annotations
Les annotations sont affichées dans un panneau latéral à côté du document. Chaque annotation montre :
- Le pseudonyme de l'auteur avec sa couleur
- La date de création
- Le contenu du commentaire
- Les éventuelles réponses
Tri des annotations
Deux modes de tri sont disponibles :
| Mode | Description |
|---|---|
| Par date | Annotations triées de la plus récente à la plus ancienne (par défaut). |
| Par position | Annotations triées dans l'ordre d'apparition dans le document, de haut en bas. |
Cliquez sur le bouton de tri pour basculer entre les deux modes.
Navigation
Cliquez sur une annotation dans le panneau latéral pour faire défiler le document jusqu'au passage surligné correspondant. Inversement, cliquez sur un surlignage dans le document pour mettre en évidence l'annotation associée dans le panneau.
Répondre à une annotation
Chaque annotation accepte des réponses en fil de discussion. Cliquez sur le bouton de réponse sous une annotation pour ajouter votre commentaire. Les réponses sont affichées en retrait sous l'annotation d'origine.
Modifier une annotation
Vous pouvez modifier vos propres annotations (identifiées par votre pseudonyme). Cliquez sur l'icône de crayon pour passer en mode édition.
Identification : L'identification repose sur le pseudonyme stocké dans le navigateur. Si vous changez de navigateur ou effacez vos données, vous ne pourrez plus modifier vos annotations précédentes.
Supprimer une annotation
Cliquez sur l'icône de suppression pour retirer votre annotation. Seul l'auteur (même pseudonyme) peut supprimer une annotation.
Annotations et versions
Les annotations sont liées à la version du document sur laquelle elles ont été créées. Lorsque le contenu du document est modifié, une nouvelle version est créée automatiquement. Les annotations de la version précédente restent visibles mais sont associées à leur version d'origine.
Activer les annotations en mode hybride
En mode hybride, les annotations sont désactivées par défaut. Pour les activer sur une page spécifique, ajoutez annotations: true dans le front matter YAML du document :
---
title: "Ma page"
weight: 10
annotations: true
---Voir la page Portail de documentation pour plus de détails sur le front matter.
Gestion des annotations (admin)
Depuis l'interface d'administration, accédez aux annotations d'un document via l'icône correspondante dans le tableau de bord. La page d'administration des annotations affiche :
- La liste complète des annotations et réponses
- Le pseudonyme et la couleur de chaque auteur
- Un filtre par auteur
- L'export au format JSON
Mises à jour en temps réel
Les annotations sont synchronisées en temps réel via Server-Sent Events (SSE). Lorsqu'un relecteur ajoute une annotation, elle apparaît automatiquement chez les autres relecteurs sans rechargement de page.