GitHub Pages SEO: A Setup Guide for Project Sites and Docs

Most GitHub Pages SEO guides stop at "add jekyll-seo-tag." That plugin helps, but it won't fix a robots.txt in the wrong folder or a docs site that Google sees on two hostnames. This guide walks through each setting in the order you'd set it, using GitHub's own docs as of September 2026.

It's the hosting half of a bigger topic. For why a docs site and a well-written repo help developer tools show up in AI answers, read our guide to GitHub READMEs as AI SEO fuel. For the repo itself, see GitHub SEO for repositories.

Pick the Site Type and Domain First

Every later GitHub Pages SEO setting depends on two choices: which kind of Pages site you run, and whether it has its own domain. GitHub's overview describes two kinds of site.

The last column is where most docs sites should end up. On a custom domain the site is a host of its own, so its robots.txt, sitemap and Search Console data all belong to it.

Set up a custom domain the safe way

GitHub recommends verifying a custom domain before adding it to a repo, to prevent takeovers. Verification uses a DNS TXT record and covers the domain's immediate subdomains. GitHub also warns against wildcard DNS records like *.example.com, which leave you open to takeovers even after you verify.

Then point DNS at GitHub. For an apex domain, GitHub's DNS docs list four A records, 185.199.108.153 through 185.199.111.153, and matching AAAA records. For a subdomain like docs.example.com, use a CNAME record to <owner>.github.io.

Two details help SEO directly:

• One hostname wins. If you set up DNS for both the apex and www, GitHub redirects one to the other automatically. GitHub recommends using a www subdomain even if you also use the apex.
• The old address redirects. In live checks on 30 September 2026, github.github.io/choosealicense.com/ returned a 301 to choosealicense.com. Your github.io URL hands its signals to the custom domain instead of competing with it.

Turn on HTTPS

GitHub says every Pages site supports HTTPS, and github.io sites created after 15 June 2016 get it automatically. For a custom domain, GitHub requests a Let's Encrypt certificate after its DNS check passes. Then tick Enforce HTTPS under Settings, Pages, per the HTTPS docs. Fix any http:// asset links, or browsers will flag mixed content.

Set Up the Build: Jekyll or GitHub Actions

Your build route decides how much GitHub Pages SEO you get without extra work. GitHub Pages builds with Jekyll by default, but GitHub's Jekyll docs now say "GitHub Actions is now the recommended approach for deploying and automating GitHub Pages sites." You have two routes.

1. Deploy from a branch. Push to a branch, and GitHub builds the root or /docs folder with Jekyll. It's the least setup, and it's limited to the plugins GitHub supports.
2. Deploy with a custom workflow. A GitHub Actions workflow builds with any static site generator you like and uploads the result. GitHub offers workflow templates for common setups, and custom workflows aren't bound by the 10-builds-per-hour soft limit.

Jekyll plugins that handle GitHub Pages SEO

GitHub's dependency versions page listed these on 30 September 2026: Jekyll 3.10.0, the github-pages gem 232, jekyll-sitemap 1.4.0, jekyll-seo-tag 2.8.0 and jekyll-redirect-from 0.16.0. A minimal _config.yml for GitHub Pages SEO looks like this:

url: "https://docs.example.com"
title: "invoice-sdk docs"
description: "Guides and API reference for the invoice-sdk Node.js library."
plugins:
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-redirect-from
social:
  links:
    - https://github.com/your-org/invoice-sdk
webmaster_verifications:
  google: your-search-console-token

List plugins under plugins. The jekyll-sitemap README warns that the GitHub Pages gem "ignores all plugins included in the Gemfile," so a plugin listed only there does nothing. Add {% seo %} to your layout's <head>.

Per its docs, jekyll-seo-tag then writes the page title, meta description, canonical URL, Open Graph and Twitter tags, and JSON-LD. The social.links list names your official profiles, such as the repo, and webmaster_verifications adds verification meta tags for Google and Bing.

GitHub Pages SEO Basics: Sitemaps, Canonicals and robots.txt

This is where most GitHub Pages SEO problems start, because the rules depend on the site type from the table above.

Sitemaps

jekyll-sitemap writes a sitemap.xml for every build. It sets <lastmod> from a last_modified_at date in front matter, or from the post date. The plugin that reads file modification dates "is not compatible with GitHub Pages auto building," so add last_modified_at by hand when you update a guide. Leave a page out with sitemap: false.

Google's sitemap guidance says a sitemap affects only URLs under its own folder unless you submit it through Search Console. A project site's /<repo>/sitemap.xml covers /<repo>/ pages, which is what you want. Submit it in Search Console anyway.

robots.txt

Google is clear that robots.txt "must be located at the root of the site host to which it applies" and "cannot be placed in a subdirectory," per its robots.txt guide. For a project site at <owner>.github.io/<repo>, the host root is <owner>.github.io. A robots.txt inside the project repo is served at /<repo>/robots.txt, and crawlers ignore it.

• On a custom domain, put robots.txt in the project's build output. If you don't add one, jekyll-sitemap's source shows it creates a robots.txt with a single Sitemap: line.
• On a github.io project site, edit the robots.txt in your <owner>.github.io repo, or skip robots.txt and use meta robots tags on the pages you want kept out.

In checks on 30 September 2026, microsoft.github.io/robots.txt and octocat.github.io/robots.txt both returned 404, which crawlers read as "no rules." To decide which AI bots to allow, see our AI crawler directory and the robots.txt tester.

Canonicals

jekyll-seo-tag builds the canonical tag from your url setting, and a page can override it with canonical_url in its front matter. Set url to your final custom domain with https://. Otherwise canonicals may point at an address that now redirects.

Redirects

Redirects are the weakest part of GitHub Pages SEO. GitHub's Pages docs don't describe custom server redirects or response headers. For moved pages, jekyll-redirect-from writes small HTML pages with a meta refresh. Google says it "interprets instant meta refresh redirects as permanent redirects," so a zero-second refresh works as a 301 for Google. For the same reason, use meta robots tags rather than an X-Robots-Tag header.

Verify the Site in Search Console

Search Console is where you find out whether your GitHub Pages SEO setup works. Google's property guide says a Domain property needs DNS verification. That works only with a custom domain, since you don't control DNS for github.io.

1. Custom domain: add a Domain property and verify with a DNS TXT record. It covers every subdomain and protocol.
2. github.io project site: add a URL-prefix property for https://<owner>.github.io/<repo>/. Verify with the HTML tag (jekyll-seo-tag's webmaster_verifications adds it) or by uploading Google's HTML file to the site.
3. Submit the sitemap under Sitemaps, then use URL Inspection on your home page and one guide to confirm Google can fetch them.

Google's verification help notes the HTML file must be reachable without a login, and removing it loses verification. Keep it in the repo. Our guide to Bing Webmaster Tools for SEO covers adding the site to Bing as well.

404 Pages, Limits and Rules

Custom 404 pages

Add a 404.html or a 404.md with permalink: /404.html front matter, per GitHub's 404 docs. In checks on 30 September 2026, jekyllrb.com, which GitHub Pages serves, returned its custom 404 page with an HTTP 404 status. Search engines won't mistake the page for real content. Link your docs home and search from it.

Usage limits and what Pages is for

These limits rarely touch GitHub Pages SEO for a docs site, but know them. GitHub's limits page, as of September 2026:

• Published sites may be no larger than 1 GB, and source repos have a recommended limit of 1 GB.
• Deployments time out after 10 minutes.
• Sites have a soft bandwidth limit of 100 GB a month and a soft limit of 10 builds an hour, except with custom Actions workflows.
• Heavy traffic may get HTTP 429 responses.

GitHub also says Pages isn't for running "your online business, e-commerce site," or "commercial software as a service (SaaS)." A docs site for an SDK, an open-source project site or a personal portfolio fits. Your product's marketing site and app belong on other hosting.

GitHub warns that Pages sites are public even when the repo is private, so strip anything sensitive before you publish. Live responses showed cache-control: max-age=600, so visitors may see updates up to 10 minutes late.

Stay clear of spam policies

Google's spam policies list "spammy accounts on hosting services that anyone can register for" as user-generated spam, and scaled content abuse covers many thin pages made to rank. Dozens of near-empty github.io sites built to catch keywords fit both. One real docs site doesn't.

Worked Example: Tallyfold's SDK Docs Site

Tallyfold is a made-up invoicing app for agencies with an open-source invoice-sdk. Its docs started as a project site at tallyfold.github.io/invoice-sdk with a robots.txt in the project repo, no sitemap and no Search Console property. Here is its GitHub Pages SEO launch checklist, with the check for each step.

The domain change fixed the robots.txt problem as a side effect: the old file in /invoice-sdk/robots.txt was never read, and on its own host the new one is. The site stayed well inside the limits, with 60 pages and about 4 MB of output against a 1 GB cap.

Step 9 needs no work. GitHub handles the redirect once the custom domain is set, as the live checks above showed.

Rankbox doesn't host sites or change GitHub settings. It helps fill a docs site with guides people search for: its Citation-Ready Writer researches the live web and writes source-backed articles, which reach your site through Rankbox's API. On a static Pages site, that means a small build step you'd wire in yourself. The Business plan is $49.50 a month with a 7-day trial on the pricing page. For free, self-hosted tools to crawl and audit your Pages site, see our list of open source SEO tools.