@mtldev514/retro-portfolio-engine 1.0.0 → 1.1.2

package/USAGE.md

@@ -0,0 +1,451 @@
+# 📖 Guide d'Utilisation - Site-as-a-Package
+
+## 🎯 Workflow Complet
+
+### Pour l'utilisateur final (qui veut son propre site)
+
+#### Étape 1 : Fork les deux repos
+
+```bash
+# 1. Fork retro-portfolio-engine (le moteur)
+# 2. Fork retro-portfolio-data (vos données)
+```
+
+#### Étape 2 : Configurer vos données
+
+```bash
+git clone https://github.com/VOTRE_USERNAME/retro-portfolio-data.git
+cd retro-portfolio-data
+
+# Modifier les fichiers de données
+nano data/painting.json
+nano lang/fr.json
+
+# Commit et push
+git add .
+git commit -m "Mon contenu personnalisé"
+git push
+```
+
+#### Étape 3 : Connecter le moteur aux données
+
+```bash
+git clone https://github.com/VOTRE_USERNAME/retro-portfolio-engine.git
+cd retro-portfolio-engine
+
+# Éditer manifest.json
+nano manifest.json
+# Changer : "owner": "VOTRE_USERNAME"
+# Changer : "repo": "retro-portfolio-data"
+# Changer : "baseUrl": "https://raw.githubusercontent.com/VOTRE_USERNAME/retro-portfolio-data/main/"
+
+git add manifest.json
+git commit -m "Configuration du data repo"
+git push
+```
+
+#### Étape 4 : Activer GitHub Pages
+
+1. Aller dans **Settings** du repo `retro-portfolio-engine`
+2. Section **Pages**
+3. Source : **GitHub Actions**
+4. Save
+
+#### Étape 5 : Déclencher le premier build
+
+1. Aller dans **Actions**
+2. Cliquer sur **Build and Deploy Site**
+3. **Run workflow** → **Run workflow**
+
+✅ Votre site sera disponible à : `https://VOTRE_USERNAME.github.io/retro-portfolio-engine/`
+
+---
+
+## 🔄 Workflow de Mise à Jour
+
+### Scénario 1 : Modifier le contenu
+
+```bash
+# Dans retro-portfolio-data
+cd retro-portfolio-data
+
+# Modifier vos données
+echo '{"items": [...]}' > data/painting.json
+
+git add data/painting.json
+git commit -m "Ajout nouvelles peintures"
+git push
+
+# Le site se rebuild automatiquement (si webhook configuré)
+# Sinon, déclencher manuellement depuis Actions
+```
+
+### Scénario 2 : Ajouter une traduction
+
+```bash
+# Dans retro-portfolio-data
+cd retro-portfolio-data
+
+# Créer nouvelle langue
+cp lang/en.json lang/es.json
+nano lang/es.json  # Traduire
+
+# Mettre à jour le manifest
+nano manifest.json
+# Ajouter "es": "lang/es.json" dans structure.lang
+
+git add .
+git commit -m "Ajout traduction espagnole"
+git push
+```
+
+### Scénario 3 : Modifier le design
+
+```bash
+# Dans retro-portfolio-engine
+cd retro-portfolio-engine
+
+# Modifier les styles
+nano style.css
+
+git add style.css
+git commit -m "Nouveau thème"
+git push
+
+# Build automatique déclenché
+```
+
+---
+
+## 🔧 Commandes Utiles
+
+### Build Local
+
+```bash
+# Build avec cache (rapide)
+./build.sh
+
+# Build complet (force download)
+./build.sh --force
+
+# Build avec manifest personnalisé
+./build.sh --manifest https://autre-repo.com/manifest.json
+
+# Spécifier répertoires
+./build.sh --cache-dir .mon-cache --output ma-dist
+
+# Aide
+./build.sh --help
+```
+
+### Test Local
+
+```bash
+# Après build
+cd dist
+python3 -m http.server 8000
+
+# Ou avec Node.js
+npx http-server dist -p 8000
+
+# Ou avec PHP
+php -S localhost:8000 -t dist
+```
+
+### Debug
+
+```bash
+# Vérifier le manifest distant
+curl https://raw.githubusercontent.com/VOTRE_USERNAME/retro-portfolio-data/main/manifest.json | jq
+
+# Tester un fichier de données
+curl https://raw.githubusercontent.com/VOTRE_USERNAME/retro-portfolio-data/main/data/painting.json | jq
+
+# Vider le cache
+rm -rf .cache
+
+# Build en mode verbose
+bash -x build.sh
+```
+
+---
+
+## 🚀 Automatisation Avancée
+
+### Option 1 : Rebuild quotidien automatique
+
+C'est déjà configuré dans `.github/workflows/build-and-deploy.yml` :
+
+```yaml
+schedule:
+  - cron: '0 0 * * *'  # Tous les jours à minuit UTC
+```
+
+### Option 2 : Webhook depuis le repo de données
+
+Créer `.github/workflows/notify-engine.yml` dans `retro-portfolio-data` :
+
+```yaml
+name: Notify Engine on Data Update
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Engine Rebuild
+        run: |
+          curl -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.ENGINE_PAT }}" \
+            https://api.github.com/repos/VOTRE_USERNAME/retro-portfolio-engine/dispatches \
+            -d '{"event_type":"data-updated"}'
+```
+
+**Configuration requise** :
+1. Créer un Personal Access Token (PAT) avec scope `repo`
+2. Ajouter dans Secrets du repo `retro-portfolio-data` : `ENGINE_PAT`
+
+### Option 3 : Build manuel avec paramètres
+
+```bash
+# Via GitHub CLI
+gh workflow run build-and-deploy.yml \
+  --repo VOTRE_USERNAME/retro-portfolio-engine \
+  -f force_rebuild=true
+
+# Via API
+curl -X POST \
+  -H "Authorization: token VOTRE_PAT" \
+  https://api.github.com/repos/VOTRE_USERNAME/retro-portfolio-engine/actions/workflows/build-and-deploy.yml/dispatches \
+  -d '{"ref":"main","inputs":{"force_rebuild":"true"}}'
+```
+
+---
+
+## 💡 Cas d'Usage
+
+### Cas 1 : Blog personnel
+
+```json
+// data/blog.json
+{
+  "posts": [
+    {
+      "id": "post-1",
+      "title": {"en": "My First Post", "fr": "Mon Premier Article"},
+      "content": {"en": "...", "fr": "..."},
+      "date": "2026-02-12"
+    }
+  ]
+}
+```
+
+### Cas 2 : Portfolio d'artiste
+
+```json
+// data/gallery.json
+{
+  "artworks": [
+    {
+      "id": "art-1",
+      "title": "Sunset",
+      "image": "https://cloudinary.com/...",
+      "description": {"en": "...", "fr": "..."}
+    }
+  ]
+}
+```
+
+### Cas 3 : Site multilingue d'entreprise
+
+```
+retro-portfolio-data/
+├── config/
+│   ├── app.json (config générale)
+│   └── languages.json (en, fr, es, de)
+├── data/
+│   ├── products.json
+│   ├── services.json
+│   └── team.json
+└── lang/
+    ├── en.json
+    ├── fr.json
+    ├── es.json
+    └── de.json
+```
+
+---
+
+## 🛠️ Personnalisation Avancée
+
+### Ajouter un nouveau type de contenu
+
+1. **Dans `retro-portfolio-data`** :
+
+```json
+// config/categories.json
+{
+  "contentTypes": [
+    {
+      "id": "videos",
+      "name": {"en": "Videos", "fr": "Vidéos"},
+      "mediaType": "video",
+      "dataFile": "data/videos.json"
+    }
+  ]
+}
+```
+
+```json
+// data/videos.json
+{
+  "items": [
+    {
+      "id": "video-1",
+      "title": "Mon premier film",
+      "url": "https://youtube.com/...",
+      "thumbnail": "..."
+    }
+  ]
+}
+```
+
+2. **Dans `retro-portfolio-engine`** :
+
+```javascript
+// js/render.js - Ajouter le renderer
+renderVideo(item) {
+    return `
+        <div class="video-item">
+            <iframe src="${item.url}"></iframe>
+            <h3>${item.title}</h3>
+        </div>
+    `;
+}
+```
+
+### Modifier le thème
+
+```css
+/* style.css */
+:root {
+    --primary-color: #your-color;
+    --font-family: 'Your-Font', sans-serif;
+}
+```
+
+### Ajouter des analytics
+
+```html
+<!-- index.html -->
+<head>
+    ...
+    <script async src="https://www.googletagmanager.com/gtag/js?id=GA_ID"></script>
+    <script>
+        window.dataLayer = window.dataLayer || [];
+        function gtag(){dataLayer.push(arguments);}
+        gtag('js', new Date());
+        gtag('config', 'GA_ID');
+    </script>
+</head>
+```
+
+---
+
+## 📊 Monitoring
+
+### Vérifier le statut du build
+
+```bash
+# Via GitHub CLI
+gh run list --repo VOTRE_USERNAME/retro-portfolio-engine
+
+# Voir les détails du dernier run
+gh run view --repo VOTRE_USERNAME/retro-portfolio-engine
+```
+
+### Voir les infos de build sur le site
+
+Le fichier `build-info.json` est généré automatiquement :
+
+```javascript
+// Dans votre site
+fetch('/build-info.json')
+    .then(r => r.json())
+    .then(info => {
+        console.log('Build date:', info.buildDate);
+        console.log('Version:', info.version);
+        console.log('Data source:', info.dataSource);
+    });
+```
+
+---
+
+## 🐛 Résolution de Problèmes
+
+### Problème : Le build échoue
+
+**Solution 1** : Vérifier les dépendances
+
+```bash
+# Installer jq si manquant
+sudo apt-get install jq
+
+# Vérifier curl
+curl --version
+```
+
+**Solution 2** : Vérifier le manifest
+
+```bash
+# Tester la validité JSON
+curl YOUR_MANIFEST_URL | jq .
+```
+
+### Problème : Les données ne se mettent pas à jour
+
+**Solution** : Forcer le rebuild
+
+```bash
+./build.sh --force
+```
+
+Ou via GitHub Actions → Run workflow → ☑️ Force rebuild
+
+### Problème : CORS errors
+
+**Solution** : GitHub raw URLs supportent CORS nativement. Vérifier que :
+
+1. L'URL est bien `raw.githubusercontent.com`
+2. Le repo de données est public
+3. Le manifest pointe vers les bons chemins
+
+### Problème : 404 sur les fichiers
+
+**Solution** : Vérifier le manifest
+
+```json
+// Doit être relatif, pas absolu
+"structure": {
+  "data": {
+    "painting": "data/painting.json"  // ✅
+    // PAS: "/data/painting.json"    // ❌
+  }
+}
+```
+
+---
+
+## 🎓 Ressources
+
+- [Documentation GitHub Pages](https://docs.github.com/pages)
+- [GitHub Actions](https://docs.github.com/actions)
+- [jq Manual](https://stedolan.github.io/jq/manual/)
+
+---
+
+**Besoin d'aide ?** Ouvrez une issue sur GitHub ! 🙌