Go back

A propos de ce site et du framework Astro

Raphaël
Updated:
Licence CC-BY

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

Illustration

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 devInstallation

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/
│   ├── layouts/
│   │   ├── Layout.astro
│   │   └── PostDetails.astro
│   ├── pages/
│   │   ├── index.astro
│   │   └── posts/
│   ├── styles/
│   │   └── global.css
│   ├── config.ts
│   └── content.config.ts
├── package.json
└── astro.config.tslayout

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, une police moderne et lisible, et Roboto Slab pour certains liens.

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.

Modifications en profondeur

après

J’ai modifié le thème pour le simplifier au maximum.

La homepage est l’élément le plus personnalisé d’un site. Le fichier pages/index.astro contient toute la structure de cette page. Pour créer une présentation minimaliste, j’ai fait le choix de supprimer toutes les sections par défaut comme les “Articles en vedette” ou les “Posts récents” en les commentant dans le code.

Le header du site est défini dans un composant séparé qui est ensuite inclus dans toutes les pages. Le thème AstroPaper propose par défaut un menu avec plusieurs entrées et un menu hamburger pour mobile. Pour simplifier la navigation, j’ai masqué certaines entrées en commentant les sections correspondantes dans le code et supprimé le menu hamburger pour garder une navigation toujours visible, même en mobile.

Le footer se trouve également dans un composant séparé. Pour ajouter des liens vers les réseaux sociaux, on utilise le fichier constants.ts qui contient un tableau SOCIALS. Chaque entrée définit un nom, une URL, un titre et une icône. Les icônes sont des fichiers SVG stockés dans le dossier assets/icons. Le composant Socials lit ce tableau et génère automatiquement les liens avec leurs icônes.

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

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 qui apparaîtra dans les listes et les moteurs de recherche"
licence: "cc-by"
---

# Mon premier article

Le contenu de l'article commence ici...src/data/blog/post.md

Le champ ogImage permet d’associer une image d’illustration qui s’affichera dans la liste des articles. Le paramètre draft permet de masquer un article en cours de rédaction. La date modDatetime se met à jour automatiquement si on l’active dans la configuration.

J’ai également créé un champ licence dont les valeurs supportées sont : cc-by, cc-by-sa, cc-by-nc, cc-by-nd, etc. Le lien généré pointe automatiquement vers la bonne page sur creativecommons.org.

Si vous souhaitez ajouter une table des matières à votre post, ajoutez simplement un titre h2 “Table of contents”.

## Table of contentssrc/data/blog/post.md

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, évitant ainsi de polluer les statistiques.

Commencez par ajouter votre identifiant Google Analytics dans le fichier config.ts :

export const SITE = {
  website: "https://monsite.com",
  author: "Raphaël",
  title: "Mon Site",
  // ... autres configurations
  googleAnalyticsId: "G-XXXXXXXXXX", // Votre ID GA4
} as const;src/config.ts

Ensuite, dans le fichier src/layouts/Layout.astro, ajoutez le code suivant dans la section head, juste après l’import des Google Fonts :

<!-- Google Analytics -->
{
  import.meta.env.PROD && SITE.googleAnalyticsId && (
    <>
      <script
        async
        src={`https://www.googletagmanager.com/gtag/js?id=${SITE.googleAnalyticsId}`}
      ></script>
      <script
        is:inline
        define:vars={{ googleAnalyticsId: SITE.googleAnalyticsId }}
      >
        window.dataLayer = window.dataLayer || [];
        function gtag() {
          dataLayer.push(arguments);
        }
        gtag("js", new Date());
        gtag("config", googleAnalyticsId);
      </script>
    </>
  )
}src/layouts/Layout.astro

Optimiser les performances

Astro propose plusieurs fonctionnalités d’optimisation automatique. Pour les images, l’utilisation du composant Image intégré permet de générer automatiquement plusieurs versions optimisées et de servir le format le plus adapté au navigateur. L’attribut loading permet de contrôler le chargement : eager pour les images visibles immédiatement, lazy pour les autres.

L’audit Astro intégré aide à identifier les problèmes de performance.

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 Docker avec Node.js
image: node:20

# Cache pour accélérer les builds
cache:
  paths:
    - node_modules/
    - .pnpm-store/

# Variables d'environnement
variables:
  PNPM_CACHE_FOLDER: .pnpm-store

# Job de build et déploiement
pages:
  stage: deploy

  script:
    # Installer pnpm
    - npm install -g pnpm

    # Installer les dépendances
    - pnpm install --frozen-lockfile

    # Build du site
    - pnpm run build

    # GitLab Pages attend les fichiers dans le dossier 'public'
    - rm -rf public
    - mv dist public

  # Artefacts à publier
  artifacts:
    paths:
      - public
    expire_in: 30 days

  # Déployer uniquement sur la branche main
  only:
    - main.gitlab-ci.yml

Points importants:

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é
  // base: "/nom-projet",  // ← Ne pas utiliser avec domaine custom

  integrations: [
    sitemap({
      filter: page => SITE.showArchives || !page.endsWith("/archives"),
    }),
  ],
  // ... reste de la config
});./astro.config.ts

Note: Si vous utilisez l’URL GitLab Pages par défaut (username.gitlab.io/projet), vous devez décommenter la ligne base: "/nom-projet".

Premier déploiement

# Ajouter tous les fichiers
git add .

# Créer le commit
git commit -m "feat: configure GitLab Pages deployment"

# Pousser vers GitLab
git push origin maingit

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.