VadimOnix/xray-decky

Site Astro (site/)

Projet pnpm autonome (son propre lockfile, pas une partie de la construction du plugin). Astro + @astrojs/sitemap + @astrojs/check. Déployé sur GitHub Pages à https://vadimonix.github.io/xray-decky/.

cd site
pnpm install
pnpm run check    # astro check — vérifie les dictionnaires de locale; porte CI
pnpm run build    # → site/dist
pnpm run dev

Contrat URL & SEO (la partie qui casse silencieusement)

Tout tient ensemble uniquement si ces points restent cohérents :

• build.format: 'preserve' → les pages plates se construisent en changelog.html, les racines de locale en ru/index.html (répertoires).
• Formes canoniques : les pages plates se terminent par .html ; les racines de locale utilisent une barre oblique finale (…/ru/) ; la racine du site est …/xray-decky/. Générées par src/lib/urls.ts (absoluteUrl, withBase, localeHref).
• Le sitemap doit correspondre exactement aux canoniques. Le hook serialize dans astro.config.mjs réécrit à la fois <loc> et les alternatives hreflang <xhtml:link> générées automatiquement : les segments de racine de locale (LOCALE_DIRS) reçoivent /, tout le reste sans extension reçoit .html. Historique : avant 2026-08, il ne réécrivait que <loc> et ajoutait .html systématiquement, envoyant les crawlers vers ru.html/zh.html/fa.html/es.html inexistants.
• L'ensemble hreflang du sitemap doit être égal à l'ensemble hreflang de la page. Base.astro émet 5 locales + x-default ; l'intégration n'émet que les 5, donc serialize ajoute x-default (= l'URL en). Google lit les annotations des deux méthodes de diffusion et traite des ensembles différents comme conflictuels, pas comme un sous-ensemble. seo-check --site les compare par URL.
• robots.txt est inactif sur ce déploiement. Il est livré vers /xray-decky/robots.txt, mais les crawlers lisent uniquement https://vadimonix.github.io/robots.txt, qui renvoie 404 (pas de dépôt utilisateur-site) — un 404 signifie "rampe tout", donc rien n'est bloqué, mais la ligne Sitemap: n'est jamais vue. La découverte du sitemap repose entièrement sur la soumission dans Search Console. Correction réelle, hors de ce dépôt : un dépôt VadimOnix/vadimonix.github.io servant un robots.txt à la racine de l'hôte, ou un domaine personnalisé.
• GitHub Pages est indulgent (fichier sans extension → 200, répertoire sans barre oblique → 301) — ne jamais s'y fier ; respecter exactement les canoniques.
• compressHTML: false est délibéré : conserve <head> (canonique, hreflang, OG, JSON-LD) facilement inspectable pour les audits SEO ; gzip compense la taille.

Ajouter une locale = un seul endroit : src/i18n/locales.ts (LOCALES, localePrefixes, hreflangCodes) + fichier dictionnaire typé par src/i18n/types.ts + LOCALE_DIRS dans astro.config.mjs + la carte locales dans la configuration de l'intégration sitemap. astro check échoue en cas de clés de dictionnaire manquantes — c'est pourquoi CI l'exécute avant la construction.

Déploiement

.github/workflows/pages.yml : se déclenche sur push vers master touchant site/** (ou le workflow lui-même). Node 22, pnpm 9, --frozen-lockfile, check → build → téléversement site/dist → déploiement. Pas de constructions PR — CI PR ne construit pas le site, donc une PR verte ne dit rien sur le site.

Vérification d'une montée de version majeure d'Astro (empirique, pas par lecture du changelog)

Dependabot ne met à jour que astro — les intégrations pair (@astrojs/sitemap, @astrojs/check) sont en retard ; vérifier qu'elles fonctionnent encore plutôt que de le supposer.

1. Construire la version mise à jour localement : pnpm install --frozen-lockfile && pnpm run check && pnpm run build.
2. Comparer la structure de dist/ avec la construction précédente (mêmes 11+ routes, répertoires de locale intacts, rien d'aplati).
3. grep -o '<loc>[^<]*</loc>' dist/sitemap-0.xml — chaque URL doit correspondre à la forme canonique d'un fichier réel.
4. Vérifier ponctuellement <link rel="canonical"> et hreflang dans dist/index.html et une page de locale.
5. Après fusion, surveiller l'exécution Pages et sonder les URL en direct (curl -s -o /dev/null -w "%{http_code}").

Seuils connus : Astro 6 nécessite Node ≥22 (pages.yml déjà sur 22) et a abandonné les configurations CJS (la nôtre est en .mjs) ; la valeur par défaut de i18n.routing.redirectToDefaultLocale a changé (sans importance ici — prefixDefaultLocale: false). Astro 7 est passé à Vite 8/Rolldown + compilateur Rust — cela affecte principalement les intégrations/configurations Vite personnalisées, que ce site n'a pas. Guides de mise à jour : https://docs.astro.build/en/guides/upgrade-to/v6/, https://docs.astro.build/en/guides/upgrade-to/v7/.

Divers

• optimize-images.sh — pipeline d'images pour public/ ; à exécuter après avoir ajouté des ressources lourdes.
• Les balises de vérification Search Console / Yandex se trouvent dans l'en-tête de la mise en page — ne pas les supprimer.
• Les règles de formulation/positionnement pour le contenu du site (et toute autre surface orientée utilisateur — README, plugin.json, métadonnées du dépôt) sont dans le skill seo-surfaces + AGENTS.md "Surfaces SEO". CI : node scripts/seo-check.mjs --site s'exécute sur dist/ dans le workflow Pages.