Today I Learned to RTFM for GitHub Pages

Before we discuss my inability to read documentation correctly, let's talk about GitHub pages for a moment. They are an awesome resource, which every developer or designer should consider for hosting their personal or project website(s). In fact, at the time of this writing, this site itself is hosted on GitHub!

Now, on to the matter at hand! GitHub has excellent documentation for GitHub Pages sites, located here. That being said, I completely missed the bit about the three different types of pages, and what each one is able to use as a content "source". When I first began setting up the repository for this site, I noticed a setting that allowed me to use the docs folder on the master branch as a content source. This was awesome, since it was akin to using a public folder alongside a src folder, like we see in so many project directory hierarchies. Without thinking twice, I renamed my repo from blog to aaw5017.github.io and took a break from the code during the work week…

Returning back over the weekend, I again visited the settings page, but did not see the docs folder option any longer! The page informed me that "User pages must be built from the master branch".

So, what was going on here? Well, it turns out I didn't RTFM, and missed the part where it clearly states that you are unable to "choose a different publishing source for user or organization sites". When I had last interacted with my repository, I renamed it, and effectively changed it from a Project Page to a User Page. That name change disallowed me from using the docs folder, and locked me into using the root of the master branch.


tl;dr

If you intend on using the docs folder within the master branch for GitHub Pages, make sure you are actually using a Project Page and not a User or Organization Page. Don't be like me; RTFM!

« Back Home