# How to improve SEO results for a GitHub Pages website

> GitHub Pages serves fast static files, which is a good start. The SEO gaps come from what it cannot do: no server redirects, no custom headers and a few URL quirks. Short answer: use a custom domain with HTTPS, publish a sitemap and robots.txt, set canonical URLs, and keep your content in real HTML.

- Page: https://liftup.tech/guides/how-to-improve-seo-results-for-a-github-pages-website/
- Type: Guide
- Updated: 2026-11-20

## In short

To improve SEO on a GitHub Pages site, use a custom domain with HTTPS enforced, publish an XML sitemap and a root robots.txt, set canonical URLs and unique titles on every page, keep content in real HTML rather than client-side rendering, and plan redirects with meta refresh or a plugin because Pages has no server-side rules.

## 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.

| Need | On a normal host | On GitHub Pages |
|---|---|---|
| 301 redirects | Server rule or CMS plugin | No server rules. Use jekyll-redirect-from, or a meta refresh page with a canonical tag as a fallback |
| Custom HTTP headers (X-Robots-Tag, cache control) | Server config | Not available. Use meta tags in the HTML |
| Proper 404 status | Automatic | Works with a 404.html at the root. Single-page-app tricks can break it |
| robots.txt location | Site root | Only works at the root of the host, so a project site under /repo-name/ cannot serve its own |
| Sitemap | Plugin or generator | jekyll-sitemap on Jekyll, or generate the file in your build step |

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 settings**: Under 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 records**: Point 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 HTTPS**: It becomes available once GitHub has issued the certificate, which can take a while after DNS settles.
4. **Choose one version**: Decide 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.

Related: [301 vs 302 redirects](https://liftup.tech/blog/301-vs-302-redirects-explained/).

## 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.

For the next step, see [technical SEO audit](https://liftup.tech/services/technical-seo/).

## 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](https://liftup.tech/services/website-development/) and [Next.js and headless builds](https://liftup.tech/services/headless-nextjs-development/) are the usual next step. For a fixed quote after a short call, go to [contact](https://liftup.tech/contact/).

## Questions, answered

### Is GitHub Pages bad for SEO?

No. Static HTML on a fast host can rank well. The weaker points are the lack of server redirects and headers, so you need to plan URLs and use meta tags carefully.

### Can I use a sitemap and robots.txt on GitHub Pages?

Yes, as plain files in your published folder. With a custom domain they sit at the site root. On a project site under username.github.io/project, robots.txt is not honored at that path because crawlers only read it at the host root.

### Do I need Jekyll?

No. Pages serves any static output. Jekyll is built in and has supported plugins, but Hugo, Astro and Eleventy work through a build action.

### Will a meta refresh redirect pass ranking signals?

Google generally treats an instant meta refresh as a permanent redirect, but a server 301 is the clearer signal. Add a canonical tag as well and avoid chains.

### Should I move off GitHub Pages for SEO?

Only if you need server redirects, headers, forms or a store. For documentation and small marketing sites, moving rarely changes rankings by itself.

## Related

- [How to improve SEO](https://liftup.tech/guides/how-to-improve-seo/)
- [Technical SEO services for sites that will not index](https://liftup.tech/services/technical-seo/)
- [Technical SEO checklist](https://liftup.tech/checklists/technical-seo-checklist/)

---

Get a fixed quote: https://liftup.tech/contact/ · email rohit@liftup.tech · WhatsApp +91 77689 10234 (https://wa.me/917768910234) · reply within one working day.
Source page: https://liftup.tech/guides/how-to-improve-seo-results-for-a-github-pages-website/ (Liftup Technologies)
