Plan for learner/instructor view

[zkamvar]

The new frontend is coming soon and we will need to make sure that we connect the wires properly.

variables

The contractor tried to separate out the common components and used jekyll templating to achieve this, which is very similar to mustache templating. The variables they used were:

• header-type : one of "software", "data", "library", or "carpentries" (I believe this will probably the incubator color as well)
• logo : takes from header-type and points to -logo.svg
• logo-sm : similar to logo, but small
• progress: the percentage of the way through the lesson by page (not taking into consideration page length).

That being said, we will need to consider the variables we already use for the header/footer.

learner/instructor view

Because we now have differing views based on learner and instructor views, we also need to reconsider how the pages will be laid out.

Right now, everything is flat, which means that all pages are at URL/page.html and there is no URL/folder/page.html. Because we now have a button that can switch between the learner and instructor view, which will have different information associated, we have different options:

Default Learner view; duplicated instructor view in nested folder

• Learner: https://carpentries.github.io/sandpaper-docs/pull-request
• Instructor https://carpentries.github.io/sandpaper-docs/ins/pull-request

For example, when I visit https://carpentries.github.io/sandpaper-docs/pull-request, I will see the default "learner view", which will have things like the glossary in the top bar, but when I click on "Instructor view", I will be taken to https://carpentries.github.io/sandpaper-docs/ins/pull-request (or maybe spell out instructor fully)

Importantly, the instructor view setting should not change if the user changes pages. The only time the instructor view should change is if the user explicitly requests a change in view from the dropdown. The most straightforward way to implement this is: make a direct copy of all HTML pages (not the assets) into the instructor/ subdirectory and make sure the assets exist.

• Pros: relatively straightforward to implement, can be accessed offline, clear labelling of URL for easy navigation between views
• Cons: increases the size of the repository and increases the build time even if lessons have no instructor components, this also increases the potential for link rot and will affect our SEO stats since /page and instructor/page are not the same (but then again, it might give us better stats to figure out who is using it 💡)

JavaScript-mediated switch

• Learner: https://carpentries.github.io/sandpaper-docs/pull-request
• Instructor: https://carpentries.github.io/sandpaper-docs/pull-request

Because the learner and instructor views would be not significantly different (instructor view allows in-document instructor notes), we might want to avoid duplication by including everything in the page and using client-side JavaScript to manipulate the DOM to show/hide the instructor note element depending on what view is selected.

• Pros: simpler SEO, lighter page, less time for build
• Cons: no direct way to access instructor page (maybe a ?query). Unknown developer time to implement because we do not have frontend expertise. Unknown how this will affect offline use.