Improve cross-site navigation in workshops (and possible outside)

[frankier]

One piece of feedback that came up again and again was that people found navigating all the different bits quite confusing. One thing that might help is a global topbar, visible across all CodeRefinery stuff people expect to use in the workshop. This includes:

• The CodeRefinery homepage (under coderefinery.org)
• The main workshop page (under coderefinery.org)
• The pages of each of the lessons (under coderefinery.github.io)
• The HedgeDoc (under notes.coderefinery.org)
• The TwichTV stream (under twitch.tv)

This might take a reasonable amount of development work, including changes to how the URLs are structured. The basic approach I propose is one similar to the webpages from my university. See here: https://www.jyu.fi/fi . At the top there is a bar which is not only injected into these pages, but also into many web applications e.g. Moodle. This works by all pages having a target HTML element and a script https://jybar.app.jyu.fi/loader.js?5 . This causes a bit of jank, but this can be mitigated a bit (e.g. make the target element the correct height).

Subtask 1: Move everything under coderefinery.org

I think it is possible to carry on using GitHub pages, and just set up a custom domain so that pages appear at github-pages.coderefinery.org, as has been done here https://github-pages.ucl.ac.uk/rsd-engineeringcourse/

For TwitchTV, it could be embedded in an iframe like so: https://dev.twitch.tv/docs/embed/everything

Subtask 2: Basic topbar (can be completed in parallel with subtask 1)

This should link to the main CodeRefinery stuff which we want accessible from anywhere. It is useful because it can at least because it can act to get back to the main site from the lessons:

• CodeRefinery Home
• Current workshop home if within 7 days
• CodeRefinery TwitchTV + Youtube combined
• CodeRefinery Lessons index
• Gear/settings -> Hide on TwitchTV

Subtask 3: In-workshop mode bar

This is the reason for the single domain. We need to set a cookie to say whether the user is in-workshop mode and which workshop they are attending.

In the in-workshop mode, the bar can show more contextual information depending on the lesson schedule. It should show:

• Workshop home or workshop schedule if it's not the same
• CodeRefinery TwitchTV
• HedgeDoc
• Display current workshop day
• Contextual
• Quit workshop mode

The way that Contextual works depends on the page, but it could be e.g.:

• On HedgeDoc
  • Previous/next HedgeDoc (go to and from archived HedgeDocs)
• On the a lesson page
  • Indicate which day the current lesson is for and what part of the day it's scheduled for (e.g. Day 2: lesson 2/3)
  • Previous/next lesson (but indicate e.g. back to the previous day's lesson, forward to next day's lesson so people know when they're going across days) (the bar Javascript gets this info from a workshop metadata JSON somewhere)
• On TwitchTV
  • Stream will start in x mins
  • Back to stream (in case people start watching the recordings)
  • View previous days on YouTube

The way to enter in-workshop mode should be a big button on the workshop web page. If this isn't possible (e.g. we want to protect the HedgeDoc) we could also have a magic link that would go in the first workshop email. If we want to get really fancy, the contents of the cookie could be protected with a MAC.

[bast]

These are all good ideas but I also want to motivate why we ended up with 2 (or more) URLs and not only 1. Because we hoped that partners and others reuse our workshop templates and run their events. Our goal was to decentralize and in some sense empower. If we bring everything under one URL, fewer people can change it.

But maybe decentralization is unrealistic and too early.

But I still think that project/organization and a particular event could be two websites.

[rkdarst]

There are some good ideas here! Once we experimented with embedding twitch at aalto: https://aaltoscicomp.github.io/scip/

I really like the idea of a consistent top bar, but can we do it without cookies?

Once, we did rename coderefinery/coderefinery.org to coderefinery/coderefinery.github.io and set the CNAME to coderefinery.org. Which did subtask (1) - but it had the unexpected consequence of redirecting everything to coderefinery.org - every lesson and every other github pages, which we didn't want at the time (it combined things that lookd like the website with things that weren't, and redirects broke the calendars for people who already had them).

Is there any way to do this without needing to be on the same domain? Rebuild every github-pages site on demand is probably doable. At least sphinx stuff could check if something should be active or not at build-time (we do something like this with coderefinery branding - it only appears if built on github). Though that's still not quite good enough for real-time updates (can that be done across domains in javascript?)

[rkdarst]

If someone can make the minimum stuff for a HTML topbar, I can start adding it to sphinx-coderefinery-branding (https://github.com/coderefinery/sphinx-coderefinery-branding) which is included in all our lessons.

[rkdarst]

repo coderefinery/lesson-topbar that builds to github-pages, and then can be loaded across the .github.io domain dynamically, somehow?

repo coderefinery/watch which can be set up as the embebded twitch and all and you go to coderefinery.github.io/watch/ ?

Do you want to be added to the coderefinery Github organizaiton (if not already there?) to work on any of these?

[frankier]

If the lessons should be "pristine" and ready for forking/whitelabeling without CodeRefinery branding, it might be possible to somehow patch in the topbar at the last moment. One slightly messy possibility would be . A neater approach would be to have another repo which includes the pristine repo, but then we have to figure out how to make this deploy too. Also it could be a bit confusing to have both pristine and coderefinery branded versions of every lesson. Perhaps the pristine versions would just be for forking and not deployed.

I also think that just the basic topbar could be useful, which wouldn't require cookies.

One way to avoid using cookies which need to be accessible on each page (which would need everything to be under coderefinery.org and require a cookie set on ".coderefinery.org"), would be for the topbar javascript to make a request to e.g. "topbar.coderefinery.org" which can set/read whichever cookies it wants from "topbar.coderefinery.org", and so working cross domain would be fine. The downside of this approach is it may cause extra jank (it but hard to say without measuring -- it might be fine and be no/only a small difference).

[frankier]

Looping back to what @bast was saying, it could a possibility to for each workshop to create a whole site where each lesson is pulled and patch a workshop topbar before deploying it. All the other stuff like Twich and HedgeDoc could still be embedded with iframes under this workshop site. The workshop could live under e.g. workshop-aut2022.coderefinery.org (short URLs so they can be typed easily). This would not require any cookies, and I think it's possible to do all of "subtask 3" this way. It may be mildly confusing if someone happens across another copy of the lesson plan, but I don't think it's such a bit problem. Another thing to consider is SEO -- the workshop lessons should probably be deindexed.

By the way, with the original topbar idea, it is just about possible to continue with the static site generator approach and not include a server component, and not put everything under ".coderefinery.org". A cross domain cookie could be implemented in Javascript using a cross origin iframe and https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage . Different versions of the topbar could be in e.g. "twitch-topbar.html" "lessons-day3-git.html" "lessons-day3-default.html". However, I am beginning to think perhaps this approach is not the best for CodeRefinery.

[frankier]

A bit more on stateful/stateless (i.e. the cookies question) Cookies (or some kind of state) are needed if we wish to limit access to the HedgeDoc to people who have recieved the email. Otherwise everyone would be able to see the HedgeDoc in the topbar. A mixed approach with a per-workshop website and a "trusted cookie" is possible.

One possible advantage of the workshop website approach is that participants can look back at the lessons exactly as they were when they took the workshop, which might be quicker than looking at substantially revised lessons.