BaseHead

BaseHead

Documentation technique

Type de ressource : Composant Astro (UI atomique)
Fichier source : src/components/BaseHead.astro
Statut : Actif

1. Vue d’ensemble

1.1. Description

Composant pour les métadonnées HTML globales de la page (meta tags, title, description, Open Graph, Twitter Card). Importe également le CSS global.

1.2. Objectif

• Centraliser les métadonnées SEO pour toutes les pages
• Assurer la cohérence des meta tags sur tout le site
• Importer le CSS global pour inclure les styles sur toutes les pages
• Fournir une image de fallback pour le partage social

1.3. Caractéristiques

Propriété	Valeur
Type	UI atomique
Hydratation	Aucune
Framework JS	Aucun
Accessibilité	Partiellement conforme (meta tags)
Responsive	Non applicable

2. Architecture et structure

2.1. Emplacement dans l’arborescence

src/components/
├── BaseHead.astro
├── Header.astro
├── Footer.astro
├── FormattedDate.astro
└── HeaderLink.astro

2.2. Composants dépendants

Composant parent	Fichier	Relation
Toutes les pages	src/pages/*.astro	Utilisation dans le <head>

2.3. Composants enfants utilisés

Composant enfant	Fichier	Rôle
Aucun	-	Composant leaf

3. Implémentation

3.1. Variante : Composant UI atomique (HTML + CSS purs)1/2

3.1. Variante : Composant UI atomique (HTML + CSS purs)2/2

src/components/BaseHead.astro

---
import '../styles/global.css';
import type { ImageMetadata } from 'astro';
import FallbackImage from '../assets/blog-placeholder-1.jpg';
import { SITE_TITLE } from '../consts';

interface Props {
  title: string;
  description: string;
  image?: ImageMetadata;
}

const canonicalURL = new URL(Astro.url.pathname, Astro.site);

const { title, description, image = FallbackImage } = Astro.props;
---

<!-- Global Metadata -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="icon" href="/favicon.ico" />
<link rel="sitemap" href="/sitemap-index.xml" />
<link
  rel="alternate"
  type="application/rss+xml"
  title={SITE_TITLE}
  href={new URL('rss.xml', Astro.site)}
/>
<meta name="generator" content={Astro.generator} />

<!-- Canonical URL -->
<link rel="canonical" href={canonicalURL} />

<!-- Primary Meta Tags -->
<title>{title}</title>
<meta name="description" content={description} />

<!-- Open Graph / Facebook -->
<meta property="og:type" content="website" />
<meta property="og:url" content={Astro.url} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={new URL(image.src, Astro.url)} />

<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image" />

3.2. Utilisation dans une page

---
import BaseHead from '../components/BaseHead.astro';
import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
---

<!doctype html>
<html lang="en">
  <head>
    <BaseHead title={SITE_TITLE} description={SITE_DESCRIPTION} />
  </head>
  <body>
    <!-- Contenu de la page -->
  </body>
</html>

4. Props et interface

4.1. Props obligatoires

Prop	Type	Description	Exemple
title	string	Titre de la page	"Accueil"
description	string	Description de la page	"Blog personnel"

4.2. Props optionnelles

Prop	Type	Description	Valeur par défaut
image	ImageMetadata	Image pour Open Graph/Twitter	FallbackImage (blog-placeholder-1.jpg)

4.3. Slots

Aucun slot n’est implémenté dans ce composant.

5. Stratégie d’hydratation

5.1. Politique d’hydratation

Type de composant	Stratégie	Rationale
Composant UI atomique	Aucune	HTML pur, pas d’interaction

5.2. Directives Astro utilisées

Aucune directive n’est utilisée (composant HTML pur).

5.3. Impact sur les performances

Métrique	Sans hydratation
HTML size	+1 KB
CSS size	+taille global.css
JS size	0 KB
TTI	Immédiat

6. Styles et design system

6.1. Utilisation des design tokens

Non applicable - ce composant n’a pas de styles inline, il importe le CSS global.

6.2. Responsive design

Non applicable - les meta tags viewport assurent le responsive design au niveau global.

6.3. Mode sombre

Non applicable - ce composant ne gère pas le mode sombre.

7. Accessibilité (a11y)

7.1. Conformité WCAG 2.1 AA

Critère	Implémentation	Statut
1.1.1 Non-text Content	Alt text non applicable (pas d’images)	N/A
1.3.1 Info and Relationships	Structure HTML sémantique (<head>, <title>)	✅
1.4.3 Contrast (Minimum)	Non applicable (pas de contenu visuel)	N/A
2.4.7 Focus Visible	Non applicable (pas d’éléments interactifs)	N/A

7.2. Attributs ARIA utilisés

Aucun attribut ARIA n’est utilisé (composant de métadonnées).

7.3. Navigation clavier

Non applicable (composant de métadonnées).

7.4. Tests d’accessibilité

# Test avec Lighthouse
npx lighthouse http://localhost:4321/ --view

8. Performance et optimisation

8.1. Optimisations appliquées

• ✅ HTML statique par défaut
• ✅ Pas de JavaScript
• ✅ Import unique du CSS global
• ✅ Canonical URL pour éviter le duplicate content

8.2. Core Web Vitals

Métrique	Objectif	Stratégie
LCP	< 2.5s	Pas de JS bloquant
INP	< 200ms	Pas de JS
CLS	< 0.1	Pas de layout shift

8.3. Taille du composant

Type	HTML	CSS	JS (hydraté)	Total
UI atomique	1 KB	+global.css	0 KB	1 KB + global.css

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Styles non appliqués	global.css non importé	Vérifier le chemin d’import
Meta tags incorrects	Props non passées	Vérifier les props title et description
Image fallback incorrecte	FallbackImage non trouvé	Vérifier le chemin de l’asset

9.2. Tests manuels

# Test local
npm run dev

# Vérification des meta tags
# Ouvrir les DevTools → Onglet Network → Recharger la page
# Vérifier les meta tags dans la réponse HTML

9.3. Logs et monitoring

Non applicable (composant statique).

10. Bonnes pratiques

10.1. Architecture

• ✅ Centraliser les métadonnées dans un composant unique
• ✅ Importer le CSS global une seule fois
• ✅ Utiliser une image de fallback pour le partage social
• ✅ Typer les props avec TypeScript

10.2. Accessibilité

• ✅ Toujours inclure un title et une description
• ✅ Utiliser les meta tags Open Graph et Twitter Card
• ✅ Inclure une canonical URL

10.3. Performance

• ✅ Pas de JavaScript inutile
• ✅ Image fallback optimisée
• ✅ Pas de styles inline

10.4. Maintenance

• ✅ Mettre à jour les meta tags selon les besoins SEO
• ✅ Vérifier la compatibilité des meta tags avec les réseaux sociaux

11. Évolutions et roadmap

11.1. Améliorations planifiées

• Ajout de meta tags supplémentaires (robots, author)
• Support du mode sombre (theme-color)
• Ajout de structured data (JSON-LD)
• Support des différentes images pour Open Graph et Twitter

11.2. Limitations connues

• ❌ Pas de support du mode sombre
• ❌ Pas de structured data
• ❌ Meta tags Twitter incomplets (twitter:title, twitter:description manquants)

12. Ressources liées

• Documentation Astro : Components
• Documentation Astro : SEO
• DAT L2 : §4 - Stratégie d’Hydratation & Gestion du JavaScript
• Composants associés :
  • src/components/Header.astro
  • src/components/Footer.astro
• Fichiers assets : src/assets/blog-placeholder-1.jpg
• CSS global : src/styles/global.css

13. Historique des modifications

Date	Version	Description	Auteur
2026-09-15	1.0	Création initiale	Devin

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

BaseHead

1. 1. Vue d’ensemble2
2. 1.1. Description3
3. 1.2. Objectif4
4. 1.3. Caractéristiques5
5. 2. Architecture et structure6
6. 2.1. Emplacement dans l’arborescence7
7. 2.2. Composants dépendants8
8. 2.3. Composants enfants utilisés9
9. 3. Implémentation10
10. 3.1. Variante : Composant UI atomique (HTML + CSS purs)11
11. 3.2. Utilisation dans une page13
12. 4. Props et interface14
13. 4.1. Props obligatoires15
14. 4.2. Props optionnelles16
15. 4.3. Slots17
16. 5. Stratégie d’hydratation18
17. 5.1. Politique d’hydratation19
18. 5.2. Directives Astro utilisées20
19. 5.3. Impact sur les performances21
20. 6. Styles et design system22
21. 6.1. Utilisation des design tokens23
22. 6.2. Responsive design24
23. 6.3. Mode sombre25
24. 7. Accessibilité (a11y)26
25. 7.1. Conformité WCAG 2.1 AA27
26. 7.2. Attributs ARIA utilisés28
27. 7.3. Navigation clavier29
28. 7.4. Tests d’accessibilité30
29. 8. Performance et optimisation31
30. 8.1. Optimisations appliquées32
31. 8.2. Core Web Vitals33
32. 8.3. Taille du composant34
33. 9. Débogage et troubleshooting35
34. 9.1. Problèmes courants36
35. 9.2. Tests manuels37
36. 9.3. Logs et monitoring38
37. 10. Bonnes pratiques39
38. 10.1. Architecture40
39. 10.2. Accessibilité41
40. 10.3. Performance42
41. 10.4. Maintenance43
42. 11. Évolutions et roadmap44
43. 11.1. Améliorations planifiées45
44. 11.2. Limitations connues46
45. 12. Ressources liées47
46. 13. Historique des modifications48