personotes/PUBLIC_NOTES.md

📚 Public Notes - Documentation

Vue d'ensemble

La fonctionnalité Public Notes permet de partager certaines notes sélectionnées avec le public, sans authentification requise. Ces notes sont converties en HTML côté serveur avec goldmark et sont accessibles via des URLs dédiées.

🔒 Architecture de sécurité

Routes publiques (sans authentification)

Les routes suivantes sont publiques et accessibles à tous :

• GET /public - Liste de toutes les notes publiques
• GET /public/view/{path} - Affichage d'une note publique en HTML

Routes protégées (nécessitent authentification en production)

Toutes les autres routes doivent être protégées par authentification :

• / - Interface principale de l'application
• /api/* - Toutes les API (édition, création, suppression)
• /api/public/toggle - Toggle du statut public (création/retrait)

IMPORTANT : L'endpoint /api/public/toggle doit être protégé car il permet de publier/dépublier des notes.

🛡️ Recommandations de sécurité

Option 1 : Authelia / Authentik (Recommandé)

Utilisez un reverse proxy avec authentification devant Personotes :

# Nginx avec Authelia
location /public {
    proxy_pass http://localhost:8080;
    # Pas d'auth pour /public
}

location / {
    proxy_pass http://localhost:8080;
    # Rediriger vers Authelia pour authentification
    auth_request /authelia;
    error_page 401 =302 https://auth.example.com;
}

Option 2 : Basic Auth Nginx

Configuration minimale pour protéger l'édition :

location /public {
    proxy_pass http://localhost:8080;
}

location / {
    proxy_pass http://localhost:8080;
    auth_basic "Personotes Admin";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Option 3 : Cloudflare Access / Zero Trust

Utilisez Cloudflare Access pour protéger toutes les routes sauf /public.

📝 Utilisation

1. Publier une note

1. Ouvrez une note dans l'éditeur
2. Cliquez sur le bouton 🔒 Privé
3. Le bouton devient 🌐 Public (vert)
4. La note est maintenant visible sur /public

Note : Le titre et les tags sont automatiquement extraits du front matter.

2. Retirer une note du public

1. Ouvrez la note publiée
2. Cliquez sur le bouton 🌐 Public
3. Le bouton redevient 🔒 Privé
4. La note n'est plus visible sur /public

3. Voir les notes publiques

Accédez à : http://votre-domaine.com/public

🌍 Internationalisation

La fonctionnalité est entièrement internationalisée :

• Anglais : Public Notes, Published on, etc.
• Français : Notes Publiques, Publié le, etc.

La langue est détectée automatiquement depuis :

1. localStorage (language key)
2. Navigateur (navigator.language)
3. Par défaut : Anglais

📂 Fichiers techniques

Backend

• internal/api/public.go - Handlers pour les notes publiques
• notes/.public.json - Liste des notes publiques (auto-généré)

Frontend

• frontend/src/public-toggle.js - Gestion du bouton Public/Privé
• templates/public-list.html - Liste des notes publiques
• templates/public-view.html - Vue d'une note publique

Traductions

• locales/en.json - Traductions anglaises (section public)
• locales/fr.json - Traductions françaises (section public)

🎨 Rendu HTML

Les notes publiques sont rendues avec goldmark (bibliothèque Go) :

• ✅ GitHub Flavored Markdown (GFM)
• ✅ Tables, strikethrough, task lists
• ✅ Syntax highlighting (highlight.js)
• ✅ Typographie intelligente (smart quotes, dashes)
• ✅ Auto-génération des IDs pour les titres

Avantages :

• SEO-friendly (HTML pré-rendu)
• Performance optimale (pas de JS requis)
• Sécurité renforcée (rendu côté serveur)
• Cache facile (HTML statique)

🔗 URLs et partage

Structure des URLs

• Liste : https://votre-domaine.com/public
• Note : https://votre-domaine.com/public/view/path/to/note.md

Partage sur réseaux sociaux

Pour améliorer le partage, vous pouvez ajouter des meta tags Open Graph dans templates/public-view.html :

<meta property="og:title" content="{{.Title}}">
<meta property="og:type" content="article">
<meta property="og:url" content="https://votre-domaine.com/public/view/{{.Path}}">
<meta property="og:description" content="Note publique partagée">

🚀 Évolutions futures possibles

• Export PDF des notes publiques
• RSS feed des notes publiques
• Sitemap XML pour SEO
• Commentaires sur les notes publiques
• Analytics (pages vues, etc.)
• Bouton "Partager" avec liens directs

❓ FAQ

Q: Les notes publiques peuvent-elles contenir des liens vers des notes privées ?

R: Oui, mais les liens vers des notes privées ne fonctionneront que pour les utilisateurs authentifiés. Pour les visiteurs publics, ils verront une erreur 403.

Q: Puis-je changer le thème des pages publiques ?

R: Oui, modifiez les templates public-list.html et public-view.html. Ils utilisent les mêmes CSS que l'application principale (static/theme.css).

Q: Comment savoir quelles notes sont publiques ?

R: Consultez le fichier notes/.public.json ou accédez à /public pour voir la liste complète.

Q: Les images dans les notes publiques fonctionnent-elles ?

R: Oui, si les images sont référencées avec des chemins absolus ou des URLs. Les chemins relatifs ne fonctionneront que si les images sont dans static/.

Q: Peut-on avoir plusieurs niveaux d'accès (public, privé, semi-privé) ?

R: Actuellement non. Il y a uniquement 2 niveaux : privé (nécessite auth) et public (accessible à tous). Pour plus de granularité, utilisez un système d'authentification avec rôles (Authelia, Authentik).

📞 Support

Pour toute question ou problème :

• GitHub Issues : https://github.com/mathieu/personotes/issues
• Documentation complète : /docs/USAGE_GUIDE.md