Configuring publishing sources for GitHub Pages

Updated on Read in 1 min

You know what sucks? Maintaining two separate branches of an open source project, just to host its source code and documentation together with GitHub Pages.

For example, my Jekyll theme’s are setup on GitHub with the following branches:

  • master holds the theme files for cloning and installing
  • gh-pages is a dupe of master with example posts and theme documentation

Anytime I push updates to master I switch to the gh-pages branch, cherry pick commits, and deal with any conflicts. Wouldn’t it be nice if there was a better way to keep everything together in a single branch?

Well there is. Under Settings there is a drop-down menu under GitHub Pages/Source that allows you to choose where to build from1.

GitHub Pages Sources

Flip the source to master branch /docs folder, move contents of gh-pages into /docs on master, and boom!

Source code and documentation in a single branch. No more switching branches and “cherry picking” for me.

  1. You can configure GitHub Pages to publish your site’s source files from master, gh-pages, or a /docs folder on your master branch for Project Pages and other Pages sites that meet certain criteria. ↩︎

Related topics:
Reply privately by email

2 mentions

  1. stefano

    i guess that’s why GitHub has made the gh-pages option difficult to find, lately

    /docs is the best indeed :)

  2. Sean

    I don’t have the drop down under GitHub Pages/Source!

Related

Using SSI to detect cookies

In my never ending quest to micro-optimize the hell out of my site, I ran into a snag when trying to use SSI directives to improve the loading of critical CSS and cached stylesheets.

Faster Netlify builds

Slowly but surely, I’ve been chipping away at my site’s build time on Netlify. There’s little left for me to optimize until Jekyll drops some nice updates in version 4.