Comment deployer un site statique avec Astro et GitHub Pages en 6 etapes

Deployer un site statique n'a jamais ete aussi simple et performant qu'en 2026. Avec Astro, le framework qui a conquis la communaute JAMstack grace a son approche « zero JavaScript par defaut », et GitHub Pages, l'hebergement gratuit integre a GitHub, vous pouvez mettre en ligne un site ultra-rapide en moins de 30 minutes. Que ce soit pour un blog, un portfolio, une documentation technique ou une landing page, cette combinaison offre des performances exceptionnelles, un deploiement automatise et un cout de zero euro. Dans ce guide, nous allons configurer l'ensemble du pipeline, de l'installation d'Astro au deploiement automatique, etape par etape.

Etape 1 : Installer Astro et initialiser le projet

La premiere etape consiste a creer un nouveau projet Astro. Astro dispose d'un CLI d'initialisation extremement bien concu qui vous guide a travers la configuration initiale. Ouvrez votre terminal et lancez la commande npm create astro@latest. Le CLI vous posera une serie de questions : le nom du projet, le template de depart (nous recommandons « blog » ou « minimal » selon votre besoin), et si vous souhaitez installer les dependances immediatement.

Pour ce tutoriel, nous allons utiliser le template blog qui inclut deja une structure de contenu avec des collections Markdown, un layout responsive et une page d'accueil. Si vous preferez partir de zero, le template « minimal » ne contient qu'un seul fichier src/pages/index.astro et vous laisse une liberte totale.

Une fois le projet cree, accedez au repertoire et lancez le serveur de developpement avec npm run dev. Astro utilise Vite sous le capot, ce qui signifie un demarrage quasi-instantane (generalement moins de 500 millisecondes) et un hot module replacement (HMR) ultra-rapide. Votre site est accessible sur http://localhost:4321 — oui, Astro utilise le port 4321 par defaut, un petit clin d'oeil numerique de l'equipe.

Explorez la structure du projet : le dossier src/pages/ contient vos pages (chaque fichier .astro devient une route), src/layouts/ contient les templates reutilisables, src/components/ vos composants, et src/content/ vos collections de contenu (articles de blog, documentation, etc.). Le fichier astro.config.mjs a la racine est le fichier de configuration central que nous modifierons a l'etape suivante.

Etape 2 : Configurer Astro pour GitHub Pages

GitHub Pages impose quelques contraintes specifiques que nous devons refleter dans la configuration d'Astro. La plus importante concerne le chemin de base (base path) : si votre site est heberge sous username.github.io/mon-projet plutot que directement sous username.github.io, vous devez configurer le parametre base en consequence.

Ouvrez le fichier astro.config.mjs et modifiez-le. La propriete site doit contenir l'URL complete de votre site GitHub Pages, par exemple https://votre-username.github.io. Si votre repository ne s'appelle pas votre-username.github.io (le repo special pour le site principal), ajoutez egalement la propriete base avec le nom de votre repository, comme /mon-projet.

Astro propose aussi des integrations utiles que vous pouvez ajouter a ce stade. L'integration @astrojs/sitemap genere automatiquement un fichier sitemap.xml a chaque build, essentiel pour le referencement SEO. L'integration @astrojs/mdx permet d'utiliser des composants JSX dans vos fichiers Markdown, ideal pour les articles de blog enrichis. Installez-les avec npx astro add sitemap mdx.

Un point crucial souvent oublie : GitHub Pages utilise Jekyll par defaut pour traiter les fichiers. Pour eviter que Jekyll n'interfere avec votre build Astro, vous devez ajouter un fichier vide nomme .nojekyll dans le dossier public/ de votre projet. Ce fichier sera copie tel quel dans le repertoire de build et indiquera a GitHub Pages de servir les fichiers sans traitement Jekyll. Sans ce fichier, les dossiers commencant par un underscore (comme _astro/, le dossier ou Astro place les assets compiles) seront ignores, et votre site apparaitra casse.

Etape 3 : Structurer le contenu avec les Content Collections

L'un des atouts majeurs d'Astro est son systeme de Content Collections, qui apporte de la structure et de la validation a votre contenu. Plutot que de simplement placer des fichiers Markdown dans un dossier et esperer que tout fonctionne, les Content Collections definissent un schema precis pour chaque type de contenu grace a Zod, la bibliotheque de validation TypeScript.

Creez un fichier src/content/config.ts pour definir vos collections. Pour un blog, votre schema typique inclurait des champs comme title (string, obligatoire), description (string, obligatoire), pubDate (date, obligatoire), updatedDate (date, optionnel), heroImage (string, optionnel), et tags (array de strings, optionnel). Astro valide chaque fichier Markdown contre ce schema au moment du build — si un article n'a pas de titre, le build echoue avec un message d'erreur clair plutot que de generer silencieusement une page cassee.

Placez ensuite vos fichiers Markdown ou MDX dans le dossier src/content/blog/. Chaque fichier doit commencer par un bloc frontmatter YAML entre des triples tirets, contenant les champs definis dans votre schema. Le nom du fichier devient automatiquement le slug de l'URL. Par exemple, mon-premier-article.md sera accessible a l'adresse /blog/mon-premier-article.

Pour generer les pages dynamiquement, creez un fichier src/pages/blog/[...slug].astro. Ce fichier utilise le routage dynamique d'Astro : la fonction getStaticPaths() recupere toutes les entrees de la collection et genere une page statique pour chacune. C'est le meme principe que Next.js avec generateStaticParams(), si vous venez de cet ecosysteme.

Etape 4 : Configurer le workflow GitHub Actions pour le deploiement automatique

C'est l'etape cle qui transforme votre projet local en un site automatiquement deploye a chaque push. Nous allons creer un workflow GitHub Actions qui build votre site Astro et le deploie sur GitHub Pages.

Creez le fichier .github/workflows/deploy.yml a la racine de votre projet. Le workflow se compose de deux jobs. Le premier job, « build », utilise l'image ubuntu-latest, installe Node.js, restaure le cache npm, installe les dependances, execute npm run build, et upload le contenu du dossier dist/ comme artifact. Le second job, « deploy », utilise l'action officielle actions/deploy-pages@v4 pour publier cet artifact sur GitHub Pages.

Le trigger principal est un push sur la branche main. Ajoutez egalement un trigger workflow_dispatch pour pouvoir declencher un deploiement manuel depuis l'interface GitHub si necessaire. Le workflow necessite les permissions pages: write et id-token: write pour interagir avec l'API GitHub Pages.

Un point important de performance : configurez le cache des dependances npm avec l'action actions/setup-node@v4 et son parametre cache: npm. Cela evite de re-telecharger toutes les dependances a chaque build et reduit le temps de deploiement de 2-3 minutes a environ 45 secondes pour un projet Astro typique. Si vous utilisez pnpm (recommande pour les projets Astro), configurez le cache pnpm de maniere similaire.

Astro fournit egalement une action officielle withastro/action@v3 qui simplifie encore davantage le workflow. Cette action gere automatiquement l'installation de Node.js, la restauration du cache, le build et l'upload de l'artifact en une seule etape. C'est l'approche recommandee pour les projets qui n'ont pas de besoins specifiques dans le pipeline de build.

Etape 5 : Activer GitHub Pages et lancer le premier deploiement

Avant que le workflow puisse deployer votre site, vous devez activer GitHub Pages dans les parametres de votre repository. Rendez-vous dans Settings > Pages et dans la section « Build and deployment », selectionnez « GitHub Actions » comme source. C'est le parametre le plus important : il indique a GitHub d'utiliser votre workflow plutot que le processus Jekyll par defaut.

Poussez votre code vers GitHub avec les commandes Git habituelles. Si vous n'avez pas encore initialise un repository Git, faites-le maintenant : initialisez le repo, ajoutez tous les fichiers, creez le premier commit, liez le remote et poussez vers la branche main. Des que le push atteint GitHub, le workflow GitHub Actions se declenche automatiquement.

Rendez-vous dans l'onglet Actions de votre repository pour suivre l'avancement du build. Le premier deploiement prend generalement entre 1 et 3 minutes, selon la taille du projet et la charge des runners GitHub. Les builds suivants seront plus rapides grace au cache des dependances. Une fois le workflow termine avec succes (coche verte), votre site est en ligne.

Votre site est desormais accessible a l'adresse https://votre-username.github.io/nom-du-repo. Verifiez que toutes les pages se chargent correctement, que les liens internes fonctionnent et que les assets (images, CSS, polices) sont bien servis. Si certains assets ne se chargent pas, verifiez que le parametre base dans astro.config.mjs correspond bien au nom de votre repository.

Etape 6 : Optimiser les performances et configurer un domaine personnalise

Votre site est en ligne, mais quelques optimisations supplementaires peuvent faire une difference significative sur les performances et l'experience utilisateur. Commencez par le composant <Image /> d'Astro, qui optimise automatiquement vos images : conversion en WebP/AVIF, redimensionnement adaptatif, lazy loading natif et generation de placeholders flous. Remplacez vos balises <img> HTML par ce composant Astro pour des gains de performance immediats.

Pour les polices de caracteres, evitez de charger Google Fonts depuis le CDN externe. Utilisez plutot le package @fontsource pour heberger les polices localement, eliminant les requetes reseau supplementaires et le FOIT (Flash of Invisible Text). Installez la police souhaitee, par exemple npm install @fontsource/inter, et importez-la dans votre layout principal.

Astro integre nativement la minification HTML et CSS. Pour aller plus loin, activez la compression des assets dans la configuration avec l'option compressHTML: true (active par defaut depuis Astro 4). Le CSS est automatiquement scope aux composants, eliminant les conflits et reduisant la taille des fichiers CSS envoyes au client.

Pour configurer un domaine personnalise, rendez-vous dans Settings > Pages > Custom domain et entrez votre nom de domaine (par exemple www.mon-site.fr). GitHub vous indiquera les enregistrements DNS a configurer chez votre registrar. Pour un apex domain (sans www), ajoutez quatre enregistrements A pointant vers les IP de GitHub Pages. Pour un sous-domaine www, ajoutez un CNAME pointant vers votre-username.github.io. Cochez egalement « Enforce HTTPS » pour activer le certificat SSL gratuit de GitHub. N'oubliez pas de mettre a jour la propriete site dans astro.config.mjs avec votre nouveau domaine et de supprimer le parametre base si vous passez a un domaine personnalise.

Enfin, testez les performances de votre site avec Google Lighthouse. Un site Astro deploye sur GitHub Pages obtient typiquement un score de 95 a 100 sur les quatre metriques (Performance, Accessibility, Best Practices, SEO). Si votre score est inferieur, les causes les plus courantes sont des images non optimisees, des polices chargees en render-blocking, ou du JavaScript tiers (analytics, widgets) non differe. Corrigez ces points et vous atteindrez les sommets.

Aller plus loin : fonctionnalites avancees d'Astro

Maintenant que votre site est deploye et optimise, explorons quelques fonctionnalites avancees d'Astro qui peuvent enrichir votre projet. L'Islands Architecture est la marque de fabrique d'Astro : elle permet d'integrer des composants interactifs (React, Vue, Svelte, Solid) dans des pages autrement 100 % statiques. Chaque composant interactif est une « ile » independante, hydratee separement. Utilisez la directive client:visible pour n'hydrater un composant que lorsqu'il entre dans le viewport, ou client:idle pour attendre que le navigateur soit inactif.

Les View Transitions d'Astro (stables depuis Astro 4) ajoutent des animations fluides entre les pages sans JavaScript supplementaire cote client, en utilisant l'API View Transitions native du navigateur. Il suffit d'ajouter le composant <ViewTransitions /> dans votre layout pour transformer votre site statique en une experience qui ressemble a une SPA (Single Page Application), tout en conservant les benefices du rendu statique.

Si votre site contient beaucoup de contenu, envisagez d'ajouter une recherche cote client avec pagefind, une bibliotheque de recherche statique qui genere un index lors du build et permet une recherche instantanee sans serveur. L'integration est simple : ajoutez le plugin Pagefind a votre build et integrez le composant de recherche dans votre layout. Le tout pese moins de 100 Ko compresse et fonctionne entierement cote client.

Pour le SEO, Astro facilite la generation de fichiers essentiels : le sitemap (via l'integration @astrojs/sitemap), le flux RSS (via @astrojs/rss), et les meta tags Open Graph. Combinee avec le score Lighthouse quasi-parfait, cette stack technique offre un excellent referencement naturel sans effort supplementaire.

FAQ