Retour

A propos de ce site

Raphaël Musitelli

Créer un site web avec Astro.build : guide pratique

Publier sur le web avec des outils libres, performants et sobres : une réflexion sur les frameworks de publication statique, à mi-chemin entre veille technologique et mise en pratique.

Illustration
Page d'accueil du présent site

Sommaire

Présentation

Astro est un framework de développement web moderne, open-source (licence MIT, 100% libre) créé en 2021, soutenu par des sponsors et une communauté active.

Il permet de créer des sites rapides et optimisés. Contrairement à d’autres outils qui chargent beaucoup de JavaScript dans le navigateur, Astro génère des pages HTML statiques, ce qui rend les sites extrêmement performants.

Comme souvent pour ce type de frameworks, Astro propose une collection de thèmes prêts à l’emploi. J’ai porté mon choix sur AstroPaper qui offre une base solide, un mode sombre et une architecture responsive. L’installation se fait en clonant le dépôt GitHub du thème et en installant les dépendances avec npm.

# cloner le repo du thème
git clone https://github.com/satnaing/astro-paper.git

# se rendre dans le répertoire
cd AstroPaper

# installer le package
npm install

# executer le site en local
npm run dev

Open browser and access : http://localhost:4321

Structure d’un projet Astro

Un site Astro s’organise autour de quelques répertoires clés. Le dossier src contient tous les fichiers sources, avec notamment les pages qui correspondent aux URLs du site, les components qui sont des morceaux réutilisables d’interface, et les layouts qui définissent la structure générale des pages. Le répertoire public contient les fichiers statiques comme les images et le favicon. Les articles de blog sont stockés dans src/data/blog sous forme de fichiers Markdown, ce qui permet d’écrire du contenu sans toucher au code.

Voici l’organisation typique d’un projet Astro avec le thème AstroPaper :

miniland/
├── public/
│   ├── favicon.svg
│   └── assets/
├── src/
│   ├── assets/
│   │   ├── icons/
│   │   └── images/
│   ├── components/
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   └── Card.astro
│   ├── data/
│   │   ├── blog/
│   │   │   ├── mon-article.md
│   │   │   └── images/
│   │   └── projects/
│   │       ├── mon-projet.md
│   │       └── images/
│   ├── layouts/
│   │   ├── Layout.astro
│   │   ├── PostDetails.astro
│   │   └── ProjectDetails.astro
│   ├── pages/
│   │   ├── index.astro
│   │   ├── a-propos.md
│   │   ├── posts/
│   │   └── projects/
│   ├── styles/
│   │   └── global.css
│   ├── config.ts
│   ├── themes.ts
│   └── content.config.ts
├── package.json
└── astro.config.ts

Personnaliser l’apparence

La personnalisation d’un thème Astro commence par la configuration de base dans le fichier config.ts. On y définit le titre du site, l’auteur, la description, et divers paramètres comme le nombre d’articles par page ou la timezone. Pour modifier l’apparence visuelle, Astro utilise Tailwind CSS, un système qui permet d’appliquer des styles directement dans le code HTML via des classes utilitaires.

Les polices de caractères se configurent dans le layout principal en ajoutant des liens vers Google Fonts dans l’en-tête HTML. Pour ce site, nous avons remplacé la police monospace par défaut par DM Sans pour le texte principal.

Les couleurs du site sont définies dans le fichier global.css avec des variables CSS. Le thème propose nativement un mode clair et un mode sombre qui basculent automatiquement selon les préférences du système.

Pour aller plus loin, j’ai centralisé les couleurs dans un fichier themes.ts qui expose des variables CSS nommées (fond, texte, accent, bordure…). Le thème actif est sélectionné dans config.ts ; les variables sont injectées dans le <head> par le layout de base. Cela permet de basculer entre palettes — actuellement Catppuccin Latte en clair et Catppuccin Macchiato en sombre — sans toucher au reste du code.

Mon choix de colorscheme ne change pas depuis quelques années : Catppuccin est le plus abouti que j’ai pu découvrir dans mes aventures de ricer linux.

catppuccin
Catppuccin palette

Modifications en profondeur

J’ai modifié en profondeur le thème AstroPaper, base technique irréprochabe et facilement modelable.

La homepage a été entièrement refondue autour d’un hero minimaliste : photo de profil, titre en dégradé et quelques liens vers les espaces de publication externe. Le fichier pages/index.astro ne contient plus aucune des sections par défaut du thème.

La navigation a été repensée : pill arrondi en desktop regroupant les liens et le bouton de thème, menu hamburger en mobile déployant le même composant. Les sections ont été renommées pour refléter leur usage : Réflexions, Laboratoire, À propos.

image
Thème AstroPaper par défaut

image
Le thème complètement retravaillé

J’ai ajouté des vignettes pour illustrer chaque article listé dans la page /posts.

La deuxième collection de contenu, Laboratoire, présente des projets distincts des articles. Chaque fiche dispose de son propre frontmatter (deployUrl, repoUrl, order) et s’affiche dans une grille de tuiles avec vignette, identique à la page Réflexions.

Légendes d’images

La syntaxe Markdown standard ne prévoit pas de légendes pour les images. Pour y remédier sans passer par du HTML brut, j’ai écrit un plugin rehype sur mesure (src/utils/rehype-image-figure.ts), branché dans astro.config.ts. Il intercepte les nœuds <img> dont l’attribut title est renseigné et les enveloppe automatiquement dans un bloc <figure><figcaption>. La syntaxe reste du Markdown pur :

![texte alternatif](./images/photo.png "La légende apparaît ici")

Le plugin détecte le titre, crée le <figure>, y déplace l’image et insère un <figcaption> avec le texte. Les styles de la légende (couleur, taille, alignement) sont définis dans typography.css.

Liens-boutons dans le contenu

Pour insérer un lien sous forme de bouton dans une page Markdown — sans passer par du HTML verbeux — une classe CSS .btn est définie dans global.css. Elle applique le style des boutons (fond coloré, bordure, icône automatique via ::before) à n’importe quel <a> :

<a href="https://..." target="_blank" class="btn">Accéder au site</a>

L’icône est injectée en CSS pur via un pseudo-élément ::before et un mask-image en data URI SVG, ce qui évite tout SVG dans le contenu.

Métadonnées des articles

Chaque article Markdown commence par un bloc de métadonnées appelé frontmatter, délimité par trois tirets. Ces informations définissent les propriétés de l’article et sont utilisées par Astro pour générer les pages et les listes. Voici un exemple typique de frontmatter pour un article :

---
author: Raphael
title: "Mon premier article"
pubDatetime: 2026-01-10T12:00:00Z
modDatetime: 2026-01-10T14:30:00Z
ogImage: "./images/illustration.png"
featured: false
draft: false
description: "Une description concise de l'article"
licence: "cc-by"
---

Ajouter Google Analytics

L’intégration de Google Analytics se fait en deux étapes. D’abord, on ajoute l’identifiant Analytics dans le fichier de configuration. Ensuite, dans le layout principal, on insère le script de tracking Google dans l’en-tête HTML. L’utilisation d’une condition import.meta.env.PROD permet de ne charger Analytics qu’en production et pas en développement local.

Déployer le site

Configuration Pipeline

Pour déployer le site, créer la configuration de la pipeline GitLab CI/CD : le fichier .gitlab-ci.yml doit se trouver à la racine du projet.

image: node:20

variables:
  PNPM_CACHE_FOLDER: .pnpm-store

pages:
  stage: deploy
  script:
    - npm install -g pnpm
    - pnpm install --frozen-lockfile
    - pnpm run build
    - rm -rf public
    - mv dist public
  artifacts:
    paths:
      - public
  only:
    - main

Configuration Domaine

Dans astro.config.ts, configurer le site pour le domaine personnalisé :

export default defineConfig({
  site: "https://www.votredomaine.com",
  // PAS de base path pour un domaine personnalisé
});

Conclusion

Après avoir, par le passé, réalisé plusieurs landing pages avec les techno Jekyll ou Hugo, je trouve le framework Astro rapide et performant. Une bonne documentation, de très nombreux thèmes, un stack technique de qualité, et tout cela sur un projet open-source !