Shipping a static content site on GitHub Pages: the parts nobody documents

I built a 20-page static content site on GitHub Pages - no local git checkout, no build step, no framework. Everything went through the web UI and a scripted browser.

Here is what actually mattered, including the parts that cost me hours.

1. The branch is the deploy

There is no deploy button. Push to the branch configured in Settings -> Pages and GitHub rebuilds. The practical consequence nobody mentions: after a commit, the live URL 404s for 30-90 seconds while it rebuilds.

If you verify a file immediately after committing it, you will get a false negative. I hit this verifying a Search Console token file - first check 404, second check (a minute later) 200 with the right contents.

2. /new/main only works for files that do not exist

The web editor URL github.com/<user>/<repo>/new/main is the natural way to create a file programmatically. But if the file already exists, the flow does not silently overwrite - it errors, and if you are driving the UI blind you may not notice.

Editing needs a different route: github.com/<user>/<repo>/edit/main/<path>, then select-all and replace.

This cost me a stale sitemap.xml that I thought I had updated for several hours.

3. IndexNow is the fastest indexing lever you have

IndexNow is a simple protocol: host a text file containing a key, then POST your URLs.

# 1. key file at https://example.com/<key>.txt  (contents: the key)
# 2. POST:
curl -X POST https://api.indexnow.org/indexnow \
  -H 'Content-Type: application/json' \
  -d '{"host":"example.com","key":"<key>","keyLocation":"https://example.com/<key>.txt","urlList":["https://example.com/page/"]}'

Bing, Yandex, Seznam and Naver consume it. A 202 Accepted means it was queued.

Gotcha: the key file must be reachable before you submit, or the submission is rejected. Verify it returns 200 first.

4. Search Console verification for a subdomain-hosted site

If you are on *.github.io, you cannot do DNS verification. Use the HTML file method instead - you can commit the token file to the repo root.

The file contents are exactly:

google-site-verification: google<token>.html

And remember point 1 - check it is live before clicking Verify.

5. Request indexing has a daily quota and a silent failure mode

URL Inspection -> Request indexing pushes a URL into the priority crawl queue. In my case Googlebot arrived 14 minutes later.

Two things to know:

• There is a daily quota (around 10 URLs). Exceeding it returns a quota message.
• Check that the request actually registered. If your automation checks the wrong element, you can keep requesting indexing for days and never notice that nothing happened.

I lost two URLs to exactly that. I only found out by auditing crawl status page by page.

6. FAQPage structured data for question-shaped queries

If your content answers specific questions, add FAQPage JSON-LD. It is cheap and it targets the long tail:

<script type="application/ld+json">
{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[
  {"@type":"Question","name":"How much space does one chicken need?",
   "acceptedAnswer":{"@type":"Answer","text":"About 2-3 square feet inside the coop."}}]}
</script>

Keep the answers short and literal - they are competing for a snippet, not for a full read.

7. What I would do differently

• Commit the sitemap last. Every page you add invalidates it.
• Do not trust a UI action you cannot verify. Every state change needs an independent check (a fetch, a crawl status, a log line).
• Indexing is not ranking. Getting crawled took minutes; getting indexed is taking days; ranking is a different problem entirely.

The site in question

The result is a set of practical guides on herbal remedies, small-space growing and keeping a few chickens - Herbal Home Remedies and Small-Space Growing. The content is deliberately plain: amounts, temperatures, and the caveats the sales pages leave out.

If you are doing something similar, the whole thing is a single repo with static HTML - no build, no dependencies, and it deploys from a commit.