189 lines
5.8 KiB
Markdown
189 lines
5.8 KiB
Markdown
# 📚 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
|
|
# 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 :
|
|
|
|
```nginx
|
|
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` :
|
|
|
|
```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`
|