GitHub Pages

This article is a stub. You can help the IndieWeb wiki by expanding it.

GitHub Pages (aka gh-pages) is a static content hosting service offered by GitHub where you can host static sites. They offer pre-built web page templates, as well as the ability to build and host Jekyll websites.

Why

Static content hosting is a form of web hosting that can be used for getting started on the IndieWeb.

Advantages

Minutes to setup at an IndieWebCamp. We have helped people get setup with GitHub static pages, buy a domain name, and make it all work together in minutes (less than 30 minutes for sure) multiple times at IndieWebCamps. Subsequently people were able to edit their website without any help.
One advantage to using a GitHub based static pages solution is that you can transfer it to another web host by deploying a set of files from GitHub to your web host.
After initial setup, you can update your site by editing it on GitHub, verifying the GitHub hosted '*.github.io' version, and then redeploying to your web host.

How

Start

The simplest way to get started with GitHub pages is:

Go https://github.com/indieweb/blank-gh-site and follow the instructions there.

Domain related configuration

configure your domain for Github Pages
- Note: when you add your custom domain to your settings page, this will automatically create a CNAME file
- Additionally, on your domain configuration page, add these two custom resource records to your DNS: an “@” type A records that points to the GitHub IPv4 address 192.30.252.153 and a “www” CNAME record that points to your USERNAME.github.io url.
enable HTTPS support
- See also: Custom domains: HTTPS Errors

In progress: How to setup your personal domain

Guides

There are several more involved guides on how (and approaches) to use GitHub Pages to host your website:

Jekyll, http://jekyllrb.com/, is enabled by default on GitHub Pages, but you can also build locally and push to GitHub.
http://opentechschool.github.io/social-coding/extras/github-pages.html
Example: BootStrap blog powered by Jekyll and GitHub pages
IndieWeb ready Jekyll project Microformats 2 ready, support for h-card in config file, receive webmentions

Fork and go

Some websites provide ready-to-fork repositories that one can use to get started. These *don't* have to be used with GitHub, but they are configured to use GitHub pages by default.

Octopress provides a rich website construction toolkit, based on top of Jekyll.
pjf.id.au has his entire website under CC-BY, with a branch on github specifically for forking the design and build process. Like Octopress, it uses Jekyll underneath. See the github repo for details.
coisas is a browser-based CMS that works only with GitHub Pages, it has a template that can be forked from the website UI, and then worked on without need of ever touching the command line.

IndieWeb Examples

Examples of IndieWeb sites hosted on Github Pages

Emma Hodge

http://emmahodge.org/

Julie Anne Noying

http://julieannenoying.com/

Chris Aldrich

Starting on 2020-04-02 Chris Aldrich has a secondary website built on TiddlyWiki that uses GitHub Pages for hosting. He's detailed the process at Self-hosting TiddlyWiki with GitHub Pages

Limitations

No HTTP Status Code Control

gh-pages does not allow you to setup custom HTTP [status] return codes. -bret (in IRC 2013-176, unlogged).

If a page exists, GitHub Pages will return "200 OK"

If a page does not exist, or was deleted, GitHub Pages will return "404 Not Found"

For some as yet unknown reason, GitHub Pages will return a 301 redirect to the same URL on the first request to a page in a "while". On subsequent requests, it will return the actual page content.

There is ongoing discussion on using http-equiv codes to work around limitations like these. See: deleted#Brainstorming

Limited file types

GitHub isn't a very good host for large media files, especially if they change, although there is nothing stopping you from uploading media. Only serve files from gh-pages, as raw repository links have to come out of some application layer, and thus are slower to retrieve. Github enforces a soft repository size limit of about 1Gb.

Jekyll Safe Mode

If you wish for GitHub to build your Jekyll website for you on their server, you must conform to the restrictions associated with jekyll safe mode, which means no plugins. You can pre-process with as many plugins as you want and upload raw html files instead as a simple workaround (similar to how octopress works).

Brainstorming

Setup your personal domain

The instructions to configure your domain for Github Pages are quite lengthy, confusing, and spread across multiple pages, this section is a simplification of those instructions for the common case of a personal domain.

Simpler step-by-step instructions:

From your *.github.io page, choose "⚙︎ Settings" near the top, then "Pages" from the left column
Scroll down to where it says "Custom domain" and enter your domain name like "example.com" (no "www." and no "/" at the end)
- You might see an error/warning like a red ⚠️ triangle next to your domain, or an error like:
  Both example.com and its alternate name are improperly configured ( Check again )
  Domain does not resolve to the GitHub Pages server. For more information, see Learn more (NotServedByPagesError). We recommend you add an A record pointed to our IP addresses, or an ALIAS record pointing to YOURUSERNAME.github.io.
- Do not worry about this, GitHub itself says
  Make sure you add your custom domain to your GitHub Pages site before configuring your custom domain with your DNS provider.
Go to the DNS configuration page for your domain (example.com) on your provider
Change the "DNS Time To Live" (TTL) to 60 seconds (some providers may set a floor of 600)
Edit existing "A" records (or create new ones if necessary) to enter GitHub’s IP addresses
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
For the latest, see step 5 in in this section where it says "To create A records, …" and copy each line of dot-separated numbers that look like "185.199.108.153" into its own "A record"
Click the ( Check again ) button in the red background warning on your GitHub settings just under the "Custom Domain" setting. (this may or may not work, depending on how many A records you edited)
Wait anywhere from a few minutes to a day (depending on what your "TTL" was set to) and reload your domain "example.com"

Criticism

As Github Pages is part of Github, it suffers from the same weakness - see the Github page for details about them.

Why