How to improve SEO results for a GitHub Pages website

What GitHub Pages gives you and what it takes away

Pages hosts static files from a repository. That means quick response times, free HTTPS and no server to patch. For documentation, portfolios, product landing pages and small marketing sites, it is a sensible choice.

The limits matter for SEO because most of the usual fixes are made at the server. Use the table to see what you must work around.

GitHub also publishes usage limits for Pages, including a recommended site size and a soft bandwidth limit, and its terms say Pages is not meant for running an online business or a store. Check the current wording before you plan anything commercial on it.

Step 1: use a custom domain, not username.github.io

A github.io address works, but you do not own the host. A custom domain keeps your rankings and links if you ever move off Pages. It also fixes the project-site problem: a site at username.github.io/project shares a host with every other project under that account, and you cannot place robots.txt or a host-level sitemap at its root.

1. Add the domain in repository settingsUnder Pages, enter the domain. GitHub creates a CNAME file in your publishing source. Keep that file in the repo or the setting resets on the next deploy.
2. Set DNS recordsPoint the apex domain with A records to the addresses GitHub lists in its documentation, and point www with a CNAME record to your username.github.io host.
3. Tick Enforce HTTPSIt becomes available once GitHub has issued the certificate, which can take a while after DNS settles.
4. Choose one versionDecide on www or the bare domain, and use that version in every canonical tag, sitemap entry and link. GitHub redirects the other form when both are set up correctly.

Step 2: add the technical basics

On Jekyll, three plugins on the supported list cover most of this: jekyll-seo-tag adds titles, canonical links, Open Graph and structured data from your front matter; jekyll-sitemap writes sitemap.xml; jekyll-feed adds an Atom feed. Set the url and baseurl values in _config.yml correctly, because the plugins build every canonical link from them. A wrong baseurl is the usual reason canonicals point at a dead path.

If you use Hugo, Eleventy, Astro or another generator, build the same outputs in your pipeline and publish the built folder with a GitHub Action.

• Write a unique title and description in front matter for every page. Default templates often repeat the site name everywhere.
• Add a robots.txt at the repo root that points to the sitemap.
• Use one H1 per page and descriptive anchor text between pages.
• Give every image width, height and alt text, and compress it. Static hosts give you no automatic image optimization.
• Link to the sitemap from Search Console and verify the domain with a DNS TXT record.

Step 3: do not let a single-page app hide your content

This is a very common GitHub Pages SEO mistake. React, Vue and similar apps use client-side routing. A deep link such as /pricing has no matching file on Pages, so visitors get a 404. The common workaround is a 404.html that redirects back to index.html. People see the page, but the server answered with a 404 status, and search engines treat that as a missing page.

Fix it by generating real HTML for every route at build time. Next.js static export, Astro, Gatsby, Eleventy and VitePress all do this. Then each URL maps to an actual file such as pricing/index.html, returns a 200 and holds the text in the first response. Check it by viewing the page source: if you see an empty div and a script tag, Google has to render JavaScript before it sees anything.

Step 4: plan redirects and URL changes before you publish

Because Pages cannot send 301 headers, a URL change costs more here than on a normal host. Choose permanent paths early. Use folder-style URLs with a trailing slash, keep them lowercase and avoid dates in the path unless the content is news.

When you must move a page, leave a stub at the old path with a canonical tag pointing to the new URL, a meta refresh with zero delay and a visible link. jekyll-redirect-from generates these stubs from front matter. Google treats a zero-second meta refresh as a permanent redirect in most cases, but it is a weaker signal than a server 301, so avoid chains and keep the old stubs for at least a year.

Pitfalls specific to Pages

• A forked or duplicated repository published on github.io can compete with your own domain. Keep the canonical tag absolute so copies point back.
• Draft or staging branches published by accident create indexable duplicates. Publish from one branch only.
• Deleting the CNAME file during a deploy breaks the domain until you restore it.
• Relying on JavaScript for navigation menus hides links from crawlers. Use real anchor tags.
• Forgetting that the site has no server logs, so use Search Console crawl stats and a privacy-friendly analytics tool instead.

If the site is outgrowing static hosting, website development and Next.js and headless builds are the usual next step. For a fixed quote after a short call, go to contact.