Render Preview for Pull Request

[kmdalton]

It would be nice if pull requests into main for rs-station.github.io rendered a preview so reviewers don't have to build the site locally.

is there a test page where the site is rendered before being merged into main? that may not be top priority, but if we wanted to up our professionalism: good idea

Originally posted by @tjlane in #46 (review)

[kmdalton]

@dennisbrookner , any thoughts on how to achieve this?

[dennisbrookner]

I have two thoughts, both of which would involve some amount of work to set up:

• make some separate repo (and/or a separate branch) that cleverly/automagically mirrors the latest build of the website. This build could then go online at some other URL, or at rs-station.github.io/test/{blah} or something.
• Once the site is built, there's a pretty small set of files that are needed to open and navigate it. If this set of files is deposited into a useful location somewhere, then without any coding or installation, a user could just open up that set of files in a browser and view a test version of the site.

I'll look more into both of these options!

[dennisbrookner]

Update: my playing around with a mirror here: https://github.com/rs-station/website-test has been fruitless, because it would require changing every url reference in the entire site into a relative url, so that the test site and the actual site don't overwrite each other. That is possible (and may have the spillover effect of making the rs-station.org base url actually stick!) but would require a lot of rewriting and clunky markdown syntax. Basically every markdown link would have to be specified as

[link text]({{ site.baseurl }}/desired_link) 

or

[link text]({{ 'desired_link' | relative_url }})

or else the link would work in the actual site, but would be either broken or misleading in the test site.

I don't think this is a good solution.

A better (or at least easier) solution is for someone who is not using their [username].github.io repo/website to volunteer their repo to serve as the test site. (I can't do it, because mine is in use.) Once that repo exists and mirrors the actual rs-station.github.io repo, we would just need to add a trigger-able workflow to that repository which grabs the latest pull request to rs-station.github.io and builds the test site. This approach would work around the nonsense with absolute vs. relative urls.

I think the best way to do this is probably to make a permanent dummy branch on the actual repo, and then any time there's a pull request into the main branch, the contents of the pull request get pushed to the dummy branch. Then, the test repo just has to mirror the dummy branch.

@kmdalton @tjlane does that sound like a reasonable solution?

[tjlane]

@dennisbrookner wow nice job digging in here

A few ideas/thoughts.

First: I like your workflow idea. Could use a dummy GH account, or maybe even better it seems like it's possible to have more than one .github.io page:
https://stackoverflow.com/questions/15563685/can-i-create-more-than-one-repository-for-github-pages

That way you don't have to force someone to give theirs up, which is also bad if that person ever changes their mind ;).

Second idea: force people to simply build the site locally and post a screenshot to get PR review approval. Downside is it's more labor for the person doing the update, and likely to be skipped/forgotten. Therefore I'm in favor of the first option if it's not too much hassle... don't make the cure worse than the disease!

[kmdalton]

The site is a pain to build on Mac, because there is already an ancient ruby installed by default. I don't think we can really expect anyone to build it locally.

[kmdalton]

Sorry... Accidentally mashed the completed button 😅.

[dennisbrookner]

First: I like your workflow idea. Could use a dummy GH account, or maybe even better it seems like it's possible to have more than one .github.io page: https://stackoverflow.com/questions/15563685/can-i-create-more-than-one-repository-for-github-pages

So I was able to create a cloned test version of the site, which lives online at https://rs-station.github.io/website-test/. The issue is that the links on the page don't get refactored; e.g. the navbar link to the About page should link to https://rs-station.github.io/website-test/about, but it actually just links to https://rs-station.github.io/about.

Funny enough though, I just realized that the page https://rs-station.github.io/website-test/about actually does exist! You just have to type in the URL manually, because the navbar won't send you there. This means that the problem is much smaller in scope than I originally thought, and I think this is workable.

[dennisbrookner]

Update: the refactoring turned out to be very simple; much more of this works automagically than I feared. Notably, markdown links do not need to be changed. A full cloned test site is now live at https://rs-station.github.io/website-test/

Next steps:

1. Temporarily remove the baseurl specification here, so that I can... (I was wrong, this parameter was never necessary! Jekyll sets the baseurl automagically for the repo.)
2. Make a PR and merge in all of these refactored relative URLs to the main website repo. These changes should be totally silent for the main repo, because in the main repo, baseurl is just an empty string, so relative and absolute URLs are the same thing.
3. Set up a workflow for automation. This might be a liiiittle bit of a pain to get working properly.

[dennisbrookner]

Update on markdown syntax. The key is that a relative link will be properly prepended with the site's url:

[contact us](contact.html)

whereas an absolute link with a leading / will never point to the test website:

[contact us](/contact.html)

I will push a quick patch that fixes this syntax, and clarifies this in the readme.

[dennisbrookner]

Update 2: I was actually wrong about markdown syntax... I'm going to put a pin in this for a moment and think more if this makes sense.

[kmdalton]

okay! let me know if i can help somehow. this is a really good feature if we can get it to work.