VadimOnix/xray-decky

Astro-Seite (site/)

Eigenständiges pnpm-Projekt (eigene Lockdatei, nicht Teil des Plugin-Builds). Astro + @astrojs/sitemap + @astrojs/check. Bereitgestellt auf GitHub Pages unter https://vadimonix.github.io/xray-decky/.

cd site
pnpm install
pnpm run check    # astro check – Typprüfung der Sprachwörterbücher; CI-Gate
pnpm run build    # → site/dist
pnpm run dev

URL- und SEO-Vertrag (der Teil, der leise zerbricht)

Alles hängt nur zusammen, wenn diese Punkte konsistent bleiben:

• build.format: 'preserve' → flache Seiten bauen zu changelog.html, Sprachwurzeln zu ru/index.html (Verzeichnisse).
• Kanonische Formen: Flache Seiten enden mit .html; Sprachwurzeln verwenden einen abschließenden Schrägstrich (…/ru/); die Seitenwurzel ist …/xray-decky/. Generiert von src/lib/urls.ts (absoluteUrl, withBase, localeHref).
• Die Sitemap muss zeichengenau mit den Kanonischen übereinstimmen. Der serialize-Hook in astro.config.mjs schreibt sowohl <loc> als auch die automatisch generierten hreflang-<xhtml:link>-Alternativen um: Sprachwurzelsegmente (LOCALE_DIRS) erhalten /, alles andere ohne Endung erhält .html. Historischer Hintergrund: Vor 2026-08 wurde nur <loc> umgeschrieben und pauschal .html angehängt, was Crawler zu nicht existierenden ru.html/zh.html/fa.html/es.html führte.
• Die Hreflang-Menge der Sitemap muss der Hreflang-Menge der Seite entsprechen. Base.astro gibt 5 Sprachen + x-default aus; die Integration gibt nur die 5 aus, daher hängt serialize x-default (= die en-URL) an. Google liest Annotationen aus beiden Auslieferungsmethoden und behandelt unterschiedliche Mengen als widersprüchlich, nicht als Teilmenge. seo-check --site vergleicht sie pro URL.
• robots.txt ist bei diesem Deploy wirkungslos. Es wird nach /xray-decky/robots.txt ausgeliefert, aber Crawler lesen nur https://vadimonix.github.io/robots.txt, das einen 404 zurückgibt (kein User-Site-Repository) – ein 404 bedeutet "crawle alles", also wird nichts blockiert, aber die Sitemap:-Zeile wird nie gesehen. Die Sitemap-Erkennung verlässt sich ausschließlich auf die Search-Console-Übermittlung. Echte Lösung außerhalb dieses Repositorys: Ein VadimOnix/vadimonix.github.io-Repository, das ein robots.txt auf Hostebene bereitstellt, oder eine benutzerdefinierte Domain.
• GitHub Pages ist nachsichtig (URL ohne Endung → 200, Verzeichnis ohne Schrägstrich → 301) – verlassen Sie sich niemals darauf; stimmen Sie genau mit den Kanonischen überein.
• compressHTML: false ist beabsichtigt: hält <head> (kanonisch, hreflang, OG, JSON-LD) für SEO-Audits durchsuchbar; gzip gleicht die Größe wieder aus.

Hinzufügen einer Sprache = eine Stelle: src/i18n/locales.ts (LOCALES, localePrefixes, hreflangCodes) + Wörterbuchdatei, typisiert durch src/i18n/types.ts + LOCALE_DIRS in astro.config.mjs + locales-Map in der Sitemap-Integrationskonfiguration. astro check schlägt bei fehlenden Wörterbuchschlüsseln fehl – deshalb führt CI es vor dem Build aus.

Deploy

.github/workflows/pages.yml: wird bei Push auf master ausgelöst, der site/** (oder die Workflow-Datei selbst) betrifft. Node 22, pnpm 9, --frozen-lockfile, check → build → upload site/dist → deploy. Keine PR-Builds – PR-CI baut die Seite nicht, daher sagt ein grüner PR nichts über die Seite aus.

Überprüfung eines Astro-Hauptversionssprungs (empirisch, nicht durch Lesen des Changelogs)

Dependabot aktualisiert nur astro – Peer-Integrationen (@astrojs/sitemap, @astrojs/check) hinken hinterher; überprüfen Sie, ob sie noch funktionieren, anstatt es anzunehmen.

1. Bauen Sie die aktualisierte Version lokal: pnpm install --frozen-lockfile && pnpm run check && pnpm run build.
2. Vergleichen Sie das Layout von dist/ mit dem vorherigen Build (gleiche 11+ Routen, Sprachverzeichnisse intakt, nichts abgeflacht).
3. grep -o '<loc>[^<]*</loc>' dist/sitemap-0.xml – jede URL muss mit der kanonischen Form einer echten Datei übereinstimmen.
4. Stichprobenartig <link rel="canonical"> und hreflang in dist/index.html und einer Sprachseite prüfen.
5. Nach dem Merge den Pages-Lauf beobachten und Live-URLs testen (curl -s -o /dev/null -w "%{http_code}").

Bekannte Grenzen: Astro 6 erfordert Node ≥22 (pages.yml bereits auf 22) und hat CJS-Konfigurationen entfernt (unsere ist .mjs); der Standardwert von i18n.routing.redirectToDefaultLocale hat sich geändert (hier irrelevant – prefixDefaultLocale: false). Astro 7 ist auf Vite 8/Rolldown + Rust-Compiler umgestiegen – betrifft hauptsächlich Integrationen/benutzerdefinierte Vite-Konfigurationen, die diese Seite nicht hat. Upgrade-Anleitungen: https://docs.astro.build/en/guides/upgrade-to/v6/, https://docs.astro.build/en/guides/upgrade-to/v7/.

Sonstiges

• optimize-images.sh – Bildverarbeitung für public/; nach dem Hinzufügen schwerer Assets ausführen.
• Suchkonsolen- / Yandex-Verifizierungs-Tags leben im Layout-Head – bitte nicht entfernen.
• Formulierungs-/Positionierungsregeln für den Seitentext (und jede andere benutzersichtbare Oberfläche – READMEs, plugin.json, Repository-Metadaten) befinden sich in der seo-surfaces-Skill + AGENTS.md "SEO Surfaces". CI: node scripts/seo-check.mjs --site wird im Pages-Workflow gegen dist/ ausgeführt.