VadimOnix/xray-decky

Site Astro (site/)

Projeto pnpm independente (próprio lockfile, não faz parte da build do plugin). Astro + @astrojs/sitemap + @astrojs/check. Implantado no GitHub Pages em https://vadimonix.github.io/xray-decky/.

cd site
pnpm install
pnpm run check    # astro check — verifica tipos dos dicionários de idioma; porta de CI
pnpm run build    # → site/dist
pnpm run dev

Contrato de URL e SEO (a parte que quebra silenciosamente)

Tudo só funciona se estes pontos permanecerem consistentes:

• build.format: 'preserve' → páginas planas são construídas como changelog.html, raízes de idioma como ru/index.html (diretórios).
• Formas canônicas: páginas planas terminam em .html; raízes de idioma usam barra invertida (…/ru/); a raiz do site é …/xray-decky/. Geradas por src/lib/urls.ts (absoluteUrl, withBase, localeHref).
• O sitemap deve corresponder exatamente aos canônicos. O hook serialize em astro.config.mjs reescreve tanto <loc> quanto as alternativas hreflang <xhtml:link> geradas automaticamente: segmentos de raiz de idioma (LOCALE_DIRS) recebem /, todo o resto sem extensão recebe .html. Histórico: antes de 2026-08 ele só reescrevia <loc> e adicionava .html indiscriminadamente, enviando crawlers para ru.html/zh.html/fa.html/es.html inexistentes.
• O conjunto hreflang do sitemap deve ser igual ao conjunto hreflang da página. Base.astro emite 5 idiomas + x-default; a integração emite apenas os 5, então o serialize adiciona x-default (= a URL en). O Google lê anotações de ambos os métodos de entrega e trata conjuntos diferentes como conflitantes, não como um subconjunto. seo-check --site compara-os por URL.
• robots.txt é inerte neste deploy. Ele é enviado para /xray-decky/robots.txt, mas os crawlers leem apenas https://vadimonix.github.io/robots.txt, que retorna 404 (sem repositório de site de usuário) — um 404 significa "arraste tudo", então nada é bloqueado, mas a linha Sitemap: nunca é vista. A descoberta do sitemap depende inteiramente da submissão no Search Console. Correção real, fora deste repositório: um repositório VadimOnix/vadimonix.github.io servindo um robots.txt na raiz do host, ou um domínio personalizado.
• GitHub Pages é tolerante (arquivo sem extensão → 200, diretório sem barra → 301) — nunca confie nisso; corresponda exatamente aos canônicos.
• compressHTML: false é intencional: mantém <head> (canônico, hreflang, OG, JSON-LD) pesquisável para auditorias de SEO; gzip recupera o tamanho.

Adicionar um idioma = um lugar: src/i18n/locales.ts (LOCALES, localePrefixes, hreflangCodes) + arquivo de dicionário tipado por src/i18n/types.ts + LOCALE_DIRS em astro.config.mjs + mapa locales na configuração da integração do sitemap. astro check falha em chaves de dicionário ausentes — é por isso que o CI executa antes da build.

Deploy

.github/workflows/pages.yml: acionado em push para master que modifica site/** (ou o próprio workflow). Node 22, pnpm 9, --frozen-lockfile, check → build → upload site/dist → deploy. Sem builds de PR — o CI de PR não constrói o site, então um PR verde não diz nada sobre o site.

Verificando um bump de versão principal do Astro (empírico, não leitura de changelog)

O Dependabot atualiza apenas astro — as integrações pares (@astrojs/sitemap, @astrojs/check) ficam para trás; verifique se ainda funcionam em vez de assumir.

1. Construa a versão atualizada localmente: pnpm install --frozen-lockfile && pnpm run check && pnpm run build.
2. Compare o layout de dist/ com a build anterior (mesmas 11+ rotas, diretórios de idioma intactos, nada achatado).
3. grep -o '<loc>[^<]*</loc>' dist/sitemap-0.xml — cada URL deve corresponder à forma canônica de um arquivo real.
4. Verifique manualmente <link rel="canonical"> e hreflang em dist/index.html e em uma página de idioma.
5. Após o merge, observe a execução do Pages e teste URLs ao vivo (curl -s -o /dev/null -w "%{http_code}").

Limites conhecidos: Astro 6 requer Node ≥22 (pages.yml já usa 22) e eliminou configurações CJS (a nossa é .mjs); o padrão de i18n.routing.redirectToDefaultLocale mudou (irrelevante aqui — prefixDefaultLocale: false). Astro 7 migrou para Vite 8/Rolldown + compilador Rust — afeta principalmente integrações/configurações Vite personalizadas, que este site não possui. Guias de atualização: https://docs.astro.build/en/guides/upgrade-to/v6/, https://docs.astro.build/en/guides/upgrade-to/v7/.

Diversos

• optimize-images.sh — pipeline de imagens para public/; execute após adicionar ativos pesados.
• Tags de verificação do Search Console / Yandex estão no cabeçalho do layout — não as remova.
• Regras de redação/posicionamento para o copy do site (e todas as outras superfícies voltadas ao usuário — READMEs, plugin.json, metadados do repositório) estão no skill seo-surfaces + AGENTS.md "SEO surfaces". CI: node scripts/seo-check.mjs --site é executado em dist/ no workflow do Pages.