personotes/EXPORT_GUIDE.md

# 📤 Export de Notes Publiques - Guide Complet

## 🎯 Concept

Les notes publiques sont **générées en fichiers HTML statiques** directement sur le serveur. Cela signifie que vous pouvez copier le dossier `public/` et le déployer sur n'importe quel serveur web (Apache, Nginx, GitHub Pages, Netlify, etc.) **sans avoir besoin de Go**.

## 🔍 Lister les notes publiques

Vous pouvez lister toutes les notes publiques avec la commande CLI intégrée :

```bash
./server list-public
```

**Sortie** :
```
📚 Notes publiques (4):

• Mon Guide
  Source: personal/guide.md
  Public: public/guide.html
  Date:   2025-11-13 20:06:21
```

Cette commande lit le fichier `notes/.public.json` et affiche :
- Le titre de chaque note
- Son chemin source
- Son chemin public
- La date de publication

## 📁 Structure générée

Quand vous publiez une note, le système génère automatiquement :

```
public/
├── index.html                  # Liste de toutes les notes publiques
├── ma-note.html               # Notes converties en HTML (structure plate)
├── autre.html
└── static/
    ├── theme.css              # Styles CSS copiés
    └── themes.css
```

**Note** : La structure est plate - toutes les notes publiques sont directement dans `public/`, peu importe leur emplacement d'origine dans vos dossiers personnels.

## 🔄 Génération automatique

### Quand une note est publiée

1. **L'utilisateur clique sur "🔒 Privé"** dans l'éditeur
2. Le système :
   - Lit le fichier Markdown
   - Extrait le front matter (titre, tags, date)
   - Convertit le Markdown en HTML avec goldmark
   - Génère un fichier HTML standalone complet
   - Copie les CSS nécessaires
   - Régénère `index.html` avec la nouvelle note
3. **Le bouton devient "🌐 Public"**

### Quand une note est retirée

1. **L'utilisateur clique sur "🌐 Public"**
2. Le système :
   - Supprime le fichier HTML correspondant
   - Régénère `index.html` sans cette note
3. **Le bouton redevient "🔒 Privé"**

## 📋 Emplacement des fichiers

- **Source** : `notes/` (vos fichiers Markdown originaux)
- **Export** : `public/` (fichiers HTML générés)
- **Index** : `.public.json` (liste des notes publiques)

## 🚀 Déploiement

### Option 1 : Copie manuelle sur serveur web

```bash
# Copier le dossier public/ sur votre serveur
scp -r public/ user@server.com:/var/www/html/notes/

# Ou avec rsync
rsync -av public/ user@server.com:/var/www/html/notes/
```

**Configuration Nginx** :
```nginx
server {
    listen 80;
    server_name notes.example.com;

    root /var/www/html/notes;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
```

**Configuration Apache** :
```apache
<VirtualHost *:80>
    ServerName notes.example.com
    DocumentRoot /var/www/html/notes

    <Directory /var/www/html/notes>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>
```

### Option 2 : GitHub Pages (gratuit)

```bash
# 1. Créer un repo GitHub
git init public/
cd public/
git add .
git commit -m "Initial public notes"

# 2. Pousser vers GitHub
git remote add origin https://github.com/username/notes-public.git
git push -u origin main

# 3. Activer GitHub Pages
# Settings → Pages → Source: main branch → Save
```

Vos notes seront disponibles à : `https://username.github.io/notes-public/`

### Option 3 : Netlify Drop (ultra simple)

1. Allez sur https://app.netlify.com/drop
2. Glissez-déposez le dossier `public/`
3. Netlify génère automatiquement une URL

### Option 4 : Vercel

```bash
cd public/
npx vercel
```

## 🔄 Automatisation avec script

Créez un script pour synchroniser automatiquement :

```bash
#!/bin/bash
# sync-public.sh

# Serveur de destination
REMOTE_USER="user"
REMOTE_HOST="server.com"
REMOTE_PATH="/var/www/html/notes"

# Synchroniser
rsync -av --delete public/ ${REMOTE_USER}@${REMOTE_HOST}:${REMOTE_PATH}

echo "✅ Notes publiques synchronisées !"
```

Utilisation :
```bash
chmod +x sync-public.sh
./sync-public.sh
```

## 🔄 Automatisation avec Git Hook

Synchroniser automatiquement après chaque publication :

```bash
# .git/hooks/post-commit
#!/bin/bash

# Si le dossier public/ a changé, synchroniser
if git diff --name-only HEAD~1 | grep -q "^public/"; then
    ./sync-public.sh
fi
```

## 📊 Avantages de cette approche

### ✅ Performance
- HTML pré-généré = temps de chargement instantané
- Pas de backend requis = moins de latence
- Cacheable à 100% par CDN

### ✅ Sécurité
- Fichiers statiques = surface d'attaque minimale
- Pas de code serveur exécuté côté public
- Isolation complète du système d'édition

### ✅ Portabilité
- Fonctionne sur **n'importe quel serveur web**
- Hébergement gratuit possible (GitHub Pages, Netlify)
- Peut être mis sur un CDN (Cloudflare, etc.)

### ✅ Simplicité
- Pas besoin de Go sur le serveur de destination
- Pas de base de données
- Juste des fichiers HTML à copier

### ✅ SEO
- HTML pré-rendu = indexation optimale par Google
- Pas de JavaScript requis pour afficher le contenu
- Meta tags facilement ajoutables

## 🎨 Personnalisation

### Modifier les styles

Les fichiers CSS sont dans `public/static/`. Vous pouvez les modifier directement :

```bash
# Éditer le CSS
nano public/static/theme.css

# Ou copier vos propres CSS
cp my-custom.css public/static/custom.css
```

### Ajouter des meta tags

Modifiez `internal/api/public.go` dans la fonction `generateStandaloneHTML()` :

```go
<head>
    <!-- Meta tags SEO -->
    <meta name="description" content="%s">
    <meta property="og:title" content="%s">
    <meta property="og:type" content="article">

    <!-- Votre titre existant -->
    <title>%s - PersoNotes</title>
```

### Ajouter Google Analytics

Ajoutez dans `generateStandaloneHTML()` avant `</head>` :

```html
<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>
```

## 🐛 Dépannage

### Les notes ne s'affichent pas

**Problème** : `/public/` retourne 404

**Solutions** :
1. Vérifier que le dossier `public/` existe : `ls -la public/`
2. Publier au moins une note pour générer le dossier
3. Redémarrer le serveur Go

### Les styles ne s'appliquent pas

**Problème** : La page s'affiche sans CSS

**Solutions** :
1. Vérifier que `public/static/theme.css` existe
2. Les chemins CSS sont relatifs : `../static/theme.css`
3. Si vous copiez ailleurs, ajustez les chemins

### Le HTML contient du Markdown brut

**Problème** : Le Markdown n'est pas converti

**Solutions** :
1. Vérifier que goldmark est installé : `go mod tidy`
2. Republier la note (toggle Private → Public)
3. Vérifier les logs du serveur

## 📝 Workflow recommandé

### Workflow quotidien

1. **Écrire** vos notes en Markdown dans l'éditeur
2. **Publier** les notes que vous voulez partager (bouton Public)
3. **Synchroniser** le dossier `public/` vers votre serveur (manuel ou automatique)

### Workflow avec Git

```bash
# 1. Publier des notes via l'interface web
# 2. Commiter les changements
git add public/
git commit -m "Publish new notes"
git push

# 3. Sur le serveur de production
git pull
# Les nouvelles notes sont disponibles !
```

## 🔐 Sécurité

### Routes publiques (pas d'auth)
- ✅ `/public/*` - Fichiers HTML statiques accessibles à tous

### Routes privées (nécessitent auth)
- 🔒 `/` - Interface d'édition
- 🔒 `/api/*` - APIs de modification
- 🔒 `/api/public/toggle` - **Protéger cet endpoint !**

### Protection recommandée

Utilisez un reverse proxy avec authentification pour protéger l'édition :

```nginx
# Nginx
location /public {
    # Pas d'auth - accessible à tous
    proxy_pass http://localhost:8080;
}

location / {
    # Auth requise pour édition
    auth_basic "Personotes Admin";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://localhost:8080;
}
```

## 📚 Ressources

- **Goldmark** : https://github.com/yuin/goldmark
- **GitHub Pages** : https://pages.github.com
- **Netlify** : https://www.netlify.com
- **Vercel** : https://vercel.com

## ❓ FAQ

**Q: Puis-je personnaliser le design des pages publiques ?**
R: Oui ! Modifiez `public/static/theme.css` ou éditez la fonction `generateStandaloneHTML()` dans `internal/api/public.go`.

**Q: Les images dans mes notes fonctionnent-elles ?**
R: Oui, si vous utilisez des URLs absolues ou si vous copiez les images dans `public/static/images/`.

**Q: Puis-je exporter vers PDF ?**
R: Les fichiers HTML peuvent être convertis en PDF avec wkhtmltopdf ou un navigateur (Imprimer → PDF).

**Q: Comment supprimer toutes les notes publiques d'un coup ?**
R: Supprimez le dossier `public/` et le fichier `.public.json`, puis relancez le serveur.

**Q: Les modifications des notes sont-elles automatiquement republiées ?**
R: Non. Si vous modifiez une note Markdown qui est déjà publique, vous devez la republier (toggle Private puis Public) pour régénérer le HTML.