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

Building a 20-page static site on GitHub Pages involved several crucial details that are often overlooked. The deployment process is automatic upon pushing to the designated branch, but there is a noticeable delay between a commit and the live URL becoming accessible, ranging from 30 to 90 seconds. Immediately after committing, a file verification may show a false negative as the live URL will still 404 for a brief period.

The URL structure "/new/main" is intended for creating new files, however, if the file already exists, an error is triggered instead of silently overwriting the existing content. This can lead to confusion and hidden errors, as was the case with a stale sitemap.xml file that took hours to realize was not updated properly.

IndexNow is a fast indexing protocol that allows hosting a key file and posting URLs for indexing. For this setup, a key file containing the verification key must be accessible before submitting the post request, or it will be rejected. The key file can also be used for Search Console verification for subdomain-hosted sites, using an HTML file containing the verification token.

Googlebot indexing requests have a daily quota and may fail silently if the daily limit is exceeded. To ensure successful indexing, check the crawl status page by page, as automated checks may not accurately reflect the outcome. For better SEO, utilize FAQPage structured data for question-based queries, as it is effective for answering specific questions and targeting long-tail searches.

Finally, it is recommended to commit the sitemap last, as every new page added invalidates the sitemap. Always verify state changes through independent checks, such as fetches or crawl statuses, rather than relying solely on UI actions. This approach avoids potential hidden errors and ensures proper deployment and indexing of the static content site on GitHub Pages.