name	astro-pages-validate-deploy
description	Ship an Astro docs site to GitHub Pages with SEO, validation, and custom-domain safety checks
domain	docs
confidence	high
source	earned

Context

Use this when an Astro site has moved beyond initial bootstrap and now needs production-safe metadata, validation, and GitHub Pages deployment behavior.

Patterns

Set one canonical production origin in astro.config.mjs; do not mix project-subpath URLs with custom-domain metadata.
Put shared SEO metadata in the base layout so every page gets canonical, Open Graph, Twitter, viewport, and robots tags by default.
Keep a small explicit route inventory for static sitemap generation when the page set is finite and intentionally hand-authored.
Add a build gate like npm run build:validate that checks built HTML for internal links, required root artifacts (CNAME, robots.txt, sitemap.xml), and basic accessibility landmarks before deploy.
Keep one committed custom-domain source of truth (for this repo, the root CNAME) and sync it into the Astro public assets before building so deploy output cannot drift from Pages configuration.
For domain cutovers, validate exact canonical and og:url values per route and fail the build if any generated artifact still contains the legacy domain.
Publish to gh-pages only after validation passes, and treat Pages configuration as incomplete until the branch exists and DNS resolves.
Keep the repository-root CNAME as the custom-domain source of truth and sync it into the Astro public output during deploy so local builds and published Pages artifacts cannot drift.

Examples

docs-site/src/layouts/BaseLayout.astro
docs-site/scripts/check-links.mjs
docs-site/src/pages/robots.txt.ts
docs-site/src/pages/sitemap.xml.ts
CNAME
.github/workflows/deploy-site.yml

Anti-Patterns

Leaving canonical URLs pointed at a GitHub project subpath after introducing a custom domain.
Letting the workflow cname, committed CNAME, and generated dist/CNAME drift apart during a domain move.
Publishing docs without validating the built output.
Calling custom-domain setup complete before both gh-pages and public DNS exist.

Más de este repositorio

mismo repositorio

central-release-version

cwoodruff/SimplicityTools

Drive package defaults, release packaging, and website version display from one MSBuild property

2026-05-022

workflow-dispatch-input-matrix

cwoodruff/SimplicityTools

Validate every meaningful workflow_dispatch input combination before approving release-pipeline changes

2026-05-022

workflow-dispatch-validation-routing

cwoodruff/SimplicityTools

Keep mixed validation/release GitHub workflow dispatch inputs from misrouting validation runs

2026-05-022

nuget-release-publish-safety

cwoodruff/SimplicityTools

Validate NuGet release artifacts before publish and ensure both package and symbol payloads are release-correct

2026-05-022

dotnet-sample-apphost

cwoodruff/SimplicityTools

Keep repo-local .NET sample apps zero-config by avoiding native apphosts when macOS integrity enforcement can kill them

2026-05-012

macos-apphost-naming

cwoodruff/SimplicityTools

Avoid `.App` executable assembly names for runnable .NET samples on macOS

2026-05-012

name	astro-pages-validate-deploy
description	Ship an Astro docs site to GitHub Pages with SEO, validation, and custom-domain safety checks
domain	docs
confidence	high
source	earned

Context

Use this when an Astro site has moved beyond initial bootstrap and now needs production-safe metadata, validation, and GitHub Pages deployment behavior.

Patterns

Set one canonical production origin in astro.config.mjs; do not mix project-subpath URLs with custom-domain metadata.
Put shared SEO metadata in the base layout so every page gets canonical, Open Graph, Twitter, viewport, and robots tags by default.
Keep a small explicit route inventory for static sitemap generation when the page set is finite and intentionally hand-authored.
Add a build gate like npm run build:validate that checks built HTML for internal links, required root artifacts (CNAME, robots.txt, sitemap.xml), and basic accessibility landmarks before deploy.
Keep one committed custom-domain source of truth (for this repo, the root CNAME) and sync it into the Astro public assets before building so deploy output cannot drift from Pages configuration.
For domain cutovers, validate exact canonical and og:url values per route and fail the build if any generated artifact still contains the legacy domain.
Publish to gh-pages only after validation passes, and treat Pages configuration as incomplete until the branch exists and DNS resolves.
Keep the repository-root CNAME as the custom-domain source of truth and sync it into the Astro public output during deploy so local builds and published Pages artifacts cannot drift.

Examples

docs-site/src/layouts/BaseLayout.astro
docs-site/scripts/check-links.mjs
docs-site/src/pages/robots.txt.ts
docs-site/src/pages/sitemap.xml.ts
CNAME
.github/workflows/deploy-site.yml

Anti-Patterns

Leaving canonical URLs pointed at a GitHub project subpath after introducing a custom domain.
Letting the workflow cname, committed CNAME, and generated dist/CNAME drift apart during a domain move.
Publishing docs without validating the built output.
Calling custom-domain setup complete before both gh-pages and public DNS exist.