Indexing GitHub Pages: The Subdomain Guide
Hosting on GitHub Pages is great, but if you are using a project site (e.g., username.github.io/my-project), things get a little tricky with SEO.
You can’t verify ownership of the entire github.io domain (obviously), so you need to tell Google specifically about your little corner of it.
The Verification Flow
Step 1: Astro Configuration
First, ensure Astro knows about your subdirectory. This is critical for generating correct sitemap links.
// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://your-username.github.io',
base: '/your-repo-name', // <--- The Magic Ingredient
integrations: [sitemap()],
});After building, check your sitemap-0.xml. The URLs MUST look like https://user.github.io/repo/page, not just https://user.github.io/page. The base config fixes this.
Step 2: Google Search Console
This is where most people get stuck.
- Go to Google Search Console.
- Click Add Property.
- STOP! Do not use the “Domain” option on the left.
- Choose URL Prefix on the right.
- Enter your full URL:
https://your-username.github.io/your-repo-name.
Step 3: Verification
Since you can’t change DNS records for github.io, you must use the HTML Tag method.
- Copy the meta tag Google gives you:
<meta name="google-site-verification" content="..." />. - Paste it into the
<head>of your mainLayout.astrofile.
<!-- src/layouts/Layout.astro -->
<head>
<!-- ... other tags ... -->
<meta name="google-site-verification" content="YOUR_CODE_HERE" />
</head>Step 4: Deploy and Verify
- Push your changes to GitHub.
- Wait for the deployment to finish.
- Go back to Search Console and click Verify.
Once verified, you can submit your sitemap URL: https://your-username.github.io/your-repo-name/sitemap-index.xml.
Mission Accomplished