Guide du projet — architecture et maintenance
Sommaire
- 1. L'idée générale
- 2. Où se trouve quoi
- Les dossiers de code (à toucher rarement)
- 3. Le cycle de travail (toujours le même)
- 4. Recettes
- 4.1 Ajouter un writeup
- 4.2 Modifier un writeup
- 4.3 Supprimer un writeup
- 4.4 Ajouter une certification
- 4.5 Une certification passe de « En cours » à « Obtenue »
- 4.6 Supprimer une certification
- 4.7 Mettre à jour le CV
- 4.8 Ajouter un projet
- 4.9 Ajouter une catégorie de projets
- 4.10 Supprimer un projet ou une catégorie
- 4.11 Mettre à jour la page « Now »
- 4.12 Changer mes infos personnelles
- 4.13 Changer un texte du menu ou d'un bouton
- 5. Cas où quelque chose ne va pas
- 6. Comment ça se déploie
- 7. Check-list avant chaque push
Portfolio cyber-yassir.com : un site statique fait avec Astro, publié sur Cloudflare Pages par GitHub Actions.
Ce guide répond à deux questions : où se trouve quoi ? et comment je fais pour… ?
1. L'idée générale
Tu écris du contenu (fichiers texte). Astro l'assemble avec des pages et composants pour fabriquer un site statique. Un git push le publie.
TU ÉCRIS ASTRO ASSEMBLE RÉSULTAT
──────── ────────────── ────────
src/content/ (writeups, src/pages/ (les URL)
certifs, src/layouts/ (cadres de page) ──► dist/
projets, now) src/components/ (briques) (site prêt)
src/config/ (tes infos) │
src/i18n/ (textes du menu) │
public/ (CV, images) ─────────────────────────────────────────────┘
▼
git push ──► GitHub Actions ──► Cloudflare Pages ──► cyber-yassir.com
Règle simple : pour 90 % des changements, tu ne touches qu'à src/content/, src/config/site.ts et public/.
2. Où se trouve quoi
| Je veux changer… | Fichier ou dossier |
|---|---|
| Un writeup | src/content/writeups/<nom>.mdx |
| Les images d'un writeup | public/images/<nom>/ |
| Une certification | src/content/certifications/<nom>.md |
| Un projet | src/content/projects/<catégorie>/… |
| Les catégories de projets (WEB, AD…) | src/config/project-categories.ts |
| La page « Now » | src/content/pages/now.md (FR) et now-en.md (EN) |
| Mon nom, bio, e-mail, liens, spécialités, timeline | src/config/site.ts |
| L'URL du site (canonical, sitemap) | src/config/site.ts → url |
| Mon CV | public/cv.pdf |
| Ma photo | public/images/avatar.webp |
| L'image de partage (LinkedIn…) | public/og-default.png |
| Un texte du menu ou d'un bouton | src/i18n/ui.ts (FR et EN) |
| Les couleurs, polices, espacements | src/styles/global.css |
| Le déploiement | .github/workflows/deploy.yml |
Les dossiers de code (à toucher rarement)
| Dossier | Rôle |
|---|---|
src/pages/ |
Chaque fichier = une URL. pages/about.astro → /about. Le dossier pages/en/ contient la version anglaise. |
src/layouts/ |
Les cadres communs : BaseLayout (tout le site), WriteupLayout, ProjectLayout. |
src/components/ |
Les briques réutilisables : cartes, badges, menu, pied de page, Callout… |
src/lib/ |
Petites fonctions utilitaires (dates, temps de lecture, lecture des projets). |
src/content.config.ts |
Les règles de chaque type de contenu (champs obligatoires, valeurs permises). |
scripts/ |
new-writeup.mjs (squelette de writeup) et l'anti-fuite de flags. |
Si un champ est invalide, le build échoue. C'est voulu : un contenu mal formé ne part jamais en ligne. Le message d'erreur donne le fichier et le champ fautif.
3. Le cycle de travail (toujours le même)
npm run dev # aperçu local : http://localhost:4321
# … tu modifies tes fichiers, tu regardes le résultat …
npm run build # contrôle final : doit finir sans erreur
git status # relis ce qui va partir
git add -A
git commit -m "Message clair"
git push # publie
Après le push :
- GitHub → onglet Actions : un run « Déployer le portfolio sur Cloudflare Pages » doit apparaître dans la minute, puis passer au vert (~1 min).
- Ouvre le site avec un rechargement forcé (
Ctrl+Shift+R).
Si aucun run n'apparaît : onglet Actions → ce workflow → Run workflow (branche main).
4. Recettes
4.1 Ajouter un writeup
-
Crée le squelette avec le script :
bashnpm run new -- --title "Forest" --platform htb --difficulty medium --os windows --template windows-adOptions :
--platform=htb | thm | ps | vh | other·--difficulty=easy | medium | hard | insane·--template=linux | windows-ad | web | generic. Le fichier est créé danssrc/content/writeups/avecstatus: WIP. -
Remplis l'en-tête (frontmatter) :
yaml--- title: "Forest" platform: "Hack The Box" # Hack The Box | TryHackMe | VulnHub | PortSwigger | OffSec Proving Grounds | Other date: 2026-11-10 difficulty: Medium # Easy | Medium | Hard | Insane category: ["ad", "windows"] # au moins 1 — sert aux filtres tags: ["kerberoasting", "dcsync"] status: Completed # Completed | WIP summary: "Au moins 20 caractères : résume la chaîne d'attaque." lab_only: true os: Windows # Linux | Windows | Other (facultatif) tools: ["nmap", "impacket"] --- -
Mets les captures dans
public/images/<nom-du-writeup>/et appelle-les ainsi dans le texte :html<figure> <img src="/images/forest/1.png" alt="Description de la capture" /> </figure> -
Encadrés : en haut du fichier,
import Callout from '../../components/Callout.astro';puis<Callout type="note" title="Lab only">…</Callout>. -
Passe
status: Completedquand c'est fini, puis suis le cycle du §3.
Protection anti-fuite. Un hook git bloque tout commit de writeup contenant un flag ou un token. Installe-le une fois par machine : npm run hooks:install. S'il bloque un commit, retire le flag du texte (ou masque-le dans la capture).
4.2 Modifier un writeup
Ouvre le .mdx, change le texte, ajoute updated: 2026-11-20 dans l'en-tête (la page affiche « maj … »). Cycle du §3.
4.3 Supprimer un writeup
git rm src/content/writeups/forest.mdx
git rm -r public/images/forest
git commit -m "Retire le writeup Forest" && git push
Son URL disparaît du site, du sitemap et du flux RSS. Pense à retirer les liens que tu aurais mis vers lui ailleurs.
4.4 Ajouter une certification
Crée src/content/certifications/nom-de-la-certif.md :
---
name: "HTB Certified Web Exploitation Specialist"
issuer: "Hack The Box Academy"
date: 2026-12-01
status: "Obtenue" # Obtenue | En cours | Visée
credential_url: "https://…" # facultatif — lien de vérification
summary: >
Une ou deux phrases sur ce que la certification valide.
---
La page /certifications (FR et EN) les trie et les affiche automatiquement.
4.5 Une certification passe de « En cours » à « Obtenue »
Trois endroits à mettre à jour, tous à la main :
- le fichier de la certification :
status: "Obtenue", ladate, et lecredential_url; - la timeline dans
src/config/site.ts(page À propos) ; src/content/pages/now.mdetnow-en.md, si le texte en parle.
4.6 Supprimer une certification
git rm src/content/certifications/nom-de-la-certif.md
4.7 Mettre à jour le CV
Remplace le fichier public/cv.pdf en gardant exactement ce nom (le bouton de la page À propos pointe sur /cv.pdf, défini par cvPath dans site.ts).
cp ~/Documents/MonCV.pdf public/cv.pdf
git add public/cv.pdf && git commit -m "Met à jour le CV" && git push
Un seul CV est proposé, pour les deux langues. Si tu veux un CV FR et un CV EN, il faudra deux fichiers et un petit changement dans about.astro et en/about.astro.
4.8 Ajouter un projet
Les projets sont rangés par catégorie dans src/content/projects/. Le nom du dossier est la catégorie.
src/content/projects/
├── web/
│ ├── sqli.md ← projet qui tient dans un seul fichier
│ └── deserialisation/ ← projet en plusieurs pages
│ ├── index.md ← fiche principale (OBLIGATOIRE)
│ └── payloads.md ← pages secondaires
├── ad/
└── reseaux/
Le frontmatter de chaque fichier :
---
title: "Désérialisation"
description: "Au moins 10 caractères."
stack: ["php", "python"] # facultatif
date: 2026-11-02
status: Active # Active | WIP | Archivé
repo_url: "https://github.com/…" # facultatif (fiche principale)
featured: false # true = carte mise en avant
order: 2 # facultatif : tri des pages d'un dossier
---
Résultat :
| Fichier | URL |
|---|---|
web/sqli.md |
/projects/web/sqli/ |
web/deserialisation/index.md |
/projects/web/deserialisation/ |
web/deserialisation/payloads.md |
/projects/web/deserialisation/payloads/ |
Règles à retenir :
- Un fichier = un projet tant qu'il tient dans une page. Passe en dossier seulement s'il te faut plusieurs pages.
- Deux niveaux maximum :
catégorie/projetoucatégorie/projet/page. - Noms de dossiers et fichiers : minuscules, sans accent ni espace (
reseaux, pasRéseaux). - Pas de
.mddirectement dansprojects/: le build échoue avec un message qui te dit où le ranger. - Dans un
.mdximbriqué, importe avec l'alias :import Callout from '@components/Callout.astro';.
4.9 Ajouter une catégorie de projets
- Dans
src/config/project-categories.ts, ajoute une entrée :ts{ slug: 'cloud', label: 'CLOUD', description: { fr: 'Cloud : …', en: 'Cloud: …' } }, - Crée le dossier
src/content/projects/cloud/avec au moins un projet.
L'ordre du tableau est l'ordre d'affichage. Une catégorie sans projet s'affiche en pointillés « Bientôt ».
4.10 Supprimer un projet ou une catégorie
git rm src/content/projects/web/sqli.md # un projet mono-fichier
git rm -r src/content/projects/web/deserialisation # un projet-dossier complet
Pour supprimer une catégorie : retire ses projets, puis son entrée dans project-categories.ts. (Un dossier absent de ce fichier s'affiche quand même, avec son nom en majuscules.)
4.11 Mettre à jour la page « Now »
Modifie les deux fichiers, src/content/pages/now.md (FR) et now-en.md (EN), et change la date updated: dans l'en-tête.
4.12 Changer mes infos personnelles
Tout est dans src/config/site.ts : nom, accroche (FR/EN), e-mail, liens sociaux, spécialités, timeline. Chaque texte affiché a une version fr et une version en : mets-les à jour ensemble.
4.13 Changer un texte du menu ou d'un bouton
src/i18n/ui.ts : une clé doit exister dans fr et dans en, sinon TypeScript signale l'erreur au build.
5. Cas où quelque chose ne va pas
| Symptôme | Cause probable | Que faire |
|---|---|---|
| Le build échoue avec un nom de champ | Frontmatter invalide (champ manquant, valeur non permise) | Corrige le champ cité ; compare avec les modèles du §4 |
| Le push est parti mais le site n'a pas changé | Aucun run GitHub Actions | Onglet Actions → Run workflow |
| Run rouge, étape « Construire le site » | Erreur de contenu ou de type | Ouvre le log, lis la 1re erreur, reproduis avec npm run build |
| Run rouge, étape « Publier » | Secrets Cloudflare manquants ou expirés | Vérifie CLOUDFLARE_API_TOKEN et CLOUDFLARE_ACCOUNT_ID dans GitHub → Settings → Secrets |
| Le commit est refusé | Hook anti-fuite : un flag est dans un writeup | Retire le flag du texte |
| Une page n'apparaît pas | Fichier mal placé ou mal nommé | Vérifie le dossier et l'extension (.md, .mdx) |
| Image cassée dans un writeup | Chemin faux | L'image doit être dans public/images/<nom>/ et appelée /images/<nom>/x.png |
Publier sans passer par GitHub (dépannage) :
npm run build
npx wrangler login # une seule fois
npx wrangler pages deploy dist --project-name=cyber-yassir --branch=main
Annuler une publication fautive (sans réécrire l'historique) :
git revert HEAD
git push
6. Comment ça se déploie
Le fichier .github/workflows/deploy.yml se lance à chaque push sur main :
- récupère le code, installe Node et les dépendances (
npm ci) ; - lance
npm run build(astro checkpuisastro build, sortie dansdist/) ; - envoie
dist/à Cloudflare Pages (projetcyber-yassir) avec deux secrets GitHub.
Il n'y a pas de connexion automatique Cloudflare ↔ dépôt : c'est ce workflow qui publie. Si Cloudflare affiche un build log sur un déploiement, c'est que l'ancienne intégration Git est encore active : déconnecte-la (Cloudflare → projet → Settings → Builds → Git repository) pour n'avoir qu'un seul déclencheur.
7. Check-list avant chaque push
-
npm run buildtermine sans erreur -
git status: seuls les fichiers voulus sont modifiés - Aucun flag, mot de passe ou token dans les textes et les captures
- Textes FR et EN à jour quand le contenu existe dans les deux langues
- Après le push : un run vert dans GitHub Actions, puis vérification sur le site