# 📚 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`