← Toutes les notes

Guide du projet — architecture et maintenance

9 min de lecture

Sommaire
  1. 1. L'idée générale
  2. 2. Où se trouve quoi
  3. Les dossiers de code (à toucher rarement)
  4. 3. Le cycle de travail (toujours le même)
  5. 4. Recettes
  6. 4.1 Ajouter un writeup
  7. 4.2 Modifier un writeup
  8. 4.3 Supprimer un writeup
  9. 4.4 Ajouter une certification
  10. 4.5 Une certification passe de « En cours » à « Obtenue »
  11. 4.6 Supprimer une certification
  12. 4.7 Mettre à jour le CV
  13. 4.8 Ajouter un projet
  14. 4.9 Ajouter une catégorie de projets
  15. 4.10 Supprimer un projet ou une catégorie
  16. 4.11 Mettre à jour la page « Now »
  17. 4.12 Changer mes infos personnelles
  18. 4.13 Changer un texte du menu ou d'un bouton
  19. 5. Cas où quelque chose ne va pas
  20. 6. Comment ça se déploie
  21. 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)

bash
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 :

  1. GitHub → onglet Actions : un run « Déployer le portfolio sur Cloudflare Pages » doit apparaître dans la minute, puis passer au vert (~1 min).
  2. 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

  1. Crée le squelette avec le script :

    bash
    npm run new -- --title "Forest" --platform htb --difficulty medium --os windows --template windows-ad
    

    Options : --platform = htb | thm | ps | vh | other · --difficulty = easy | medium | hard | insane · --template = linux | windows-ad | web | generic. Le fichier est créé dans src/content/writeups/ avec status: WIP.

  2. 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"]
    ---
    
  3. 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>
    
  4. Encadrés : en haut du fichier, import Callout from '../../components/Callout.astro'; puis <Callout type="note" title="Lab only">…</Callout>.

  5. Passe status: Completed quand 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

bash
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 :

markdown
---
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 :

  1. le fichier de la certification : status: "Obtenue", la date, et le credential_url ;
  2. la timeline dans src/config/site.ts (page À propos) ;
  3. src/content/pages/now.md et now-en.md, si le texte en parle.

4.6 Supprimer une certification

bash
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).

bash
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 :

yaml
---
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/projet ou catégorie/projet/page.
  • Noms de dossiers et fichiers : minuscules, sans accent ni espace (reseaux, pas Réseaux).
  • Pas de .md directement dans projects/ : le build échoue avec un message qui te dit où le ranger.
  • Dans un .mdx imbriqué, importe avec l'alias : import Callout from '@components/Callout.astro';.

4.9 Ajouter une catégorie de projets

  1. Dans src/config/project-categories.ts, ajoute une entrée :
    ts
    { slug: 'cloud', label: 'CLOUD',
      description: { fr: 'Cloud : …', en: 'Cloud: …' } },
    
  2. 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

bash
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) :

bash
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) :

bash
git revert HEAD
git push

6. Comment ça se déploie

Le fichier .github/workflows/deploy.yml se lance à chaque push sur main :

  1. récupère le code, installe Node et les dépendances (npm ci) ;
  2. lance npm run build (astro check puis astro build, sortie dans dist/) ;
  3. envoie dist/ à Cloudflare Pages (projet cyber-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 build termine 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