Need Help With Jekyll GitHub Project Page and Team Git Workflow

I have published http://cppalliance.com from https://github.com/CPPAlliance/cppalliance.github.io

As you can see, there’s a CNAME. Everything is great, the page renders as it should and when I push changes the pages get rebuilt.

However, multiple people are working on this now. Similarly to how a team might collaborate on building a C++ program, I have made a fork of the repository in my personal account:
https://github.com/vinniefalco/cppalliance

Now I can make changes, rebase, squash, fold, and generally arrange the branch any way that I want before submitting it as a pull request to the upstream repository. A problem arises, how to preview the changes before the merge? Well, I can visit the Project GitHub Page:
https://vinniefalco.github.io/cppalliance/

I can see some of my content, but where did the style sheet go? Is this because the URI is not a root target?

I am also getting an error in my email about the CNAME being taken. Well, that makes sense. We can’t have every fork also be aliased to cppalliance.com. But I also don’t want to get this error every time. I could delete the CNAME file from my fork, but that would create headaches when merging the submitted pull request to the upstream repository. Is there a way to disable the CNAME from my fork’s Project’s settings? I don’t see it - consider adding it.

Anyway, I would very much like to get to a point where the team members can preview change to their individual forks before submitting the pull request, using the wonderful GitHub Project Pages mechanism described in the docs.

Any advice?

Thanks

Hi Vinnie!

I’m afraid to say that GitHub Pages sites with custom domains don’t play especially well with forks at the moment. For now, there isn’t a way to supress the CNAME warnings, other than configuring an email filter on your end to automatically archive these messages. It’s not the most elegant solution, but it does work.

Another alternative is to bypass publishing the fork altogether, and instead use a local Jekyll environment to test changes offline. We have documentation here on how to get that set up:

https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/

Of course, we’re aware that this could be better, and it is something that we’d like to improve in the future. I can’t make any promises, but I’ll certainly communicate your observations to our team!

Finally, there’s the CSS issue you mentioned – this isn’t specific to GitHub Pages, but is rather a general HTML concept. At the moment, the CSS file is referenced as:

href="/css/main.css"

The leading slash before “css” there represents the root of the published URL. This works just fine when the site is published at http://cppalliance.com, but causes trouble when published at https://username.github.io/cppalliance.github.io. That’s because the slash will end up referring to https://username.github.io (the root of the domain), not the relevant “cppalliance.github.io” subdirectory, where the CSS file is actually stored.

The simplest solution to this trouble is to remove the leading slash, leaving you with the following:

href="css/main.css"

This construction tells the browser to look for a “css” folder within whatever directory the index.html page is being published from, and should therefore function perfectly regardless of which domain the site is published at. You can learn more about HTML file paths here:

https://www.w3schools.com/html/html_filepaths.asp

I hope that helps!

1 Like