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

The best thing I have found so far is to

  • Fork the repo,
  • Change the CNAME right away
    • to a domain you have access to like “{NewCname}.PersonalDomain.com”
    • Configure your Domain’s public DNS and ensure Github Pages is enabled in the Settings of your Forked Repo
      • or Delete the CNAME file entirely by itself
    • after it finishes deploying, access at your new Cname through https:// NewCname.PersonalDomain .com or https:// github .com/ForkedUserName/RepoName depending on if you changed or deleted the CNAME
  • cherry pick the Commits you are including in your pull requests to upstream later on and skip the Commit where you changed the CNAME file, sadly it doesn’t look like there is a way to Cherry Pick in the current Github Desktop or WebUI that I can find

Another alternative I was finding was essentially to clear the file from the Index in the fork and skip the file from (https:// stackoverflow .com/a/45021381/2238544) checking for things to commit or other methods to revert automatically ( https:// stackoverflow .com/a/25315991/2238544) but they seem similarly awful

Possibly a pre-receive hook (https:// docs.github .com/en/enterprise-server@2.21/github/collaborating-with-issues-and-pull-requests/working-with-pre-receive-hooks ) looks promising, though I don’t think that would be available on Github.com, only the enterprise server

Or possibly Compliance Items and/or Webhooks (https://resources.github .com/whitepapers/practical-guide-to-CI-with-Jenkins-and-GitHub/ ), but I haven’t gotten into that yet, and that might fit best on the Upstream Repo, not just your fork

PS Sorry about the awful links, it was blocking me from posting more than two links since I’m a new user