Mechanisms for managing workshop websites and install instructions

[jduckles]

I'd still like to see something like #305 (which has gone stale), particularly as we add more carpentries and more lessons, we want webpage setup to be easy. Right now it isn't so easy, the instructor has to edit several files in several different directories. #415 Talks about making the template more user-friendly, but any solution must work without having to install some dependency on the local machine. Ideally we can come up with something that leverages Jekyll on the backend and works using the GitHub text editor.

To prepare for the long-term growth in the number of lessons we are experiencing in the community I'd like to see an approach where install instructions from the lessons being taught are in the lessons themselves and can be embedded in the workshop website. Using the short github username/repo style links we could automate much of this by bringing in the install instructions from each lesson repo itself.

lessons: ["swcarpentry/shell-novice", "swcarpentry/git-novice", "swcarpentry/python-inflammation"]

Then we can have an <iframe> that embeds setup.html instructions from each item in lessons into the workshop page. Any gotchas or pitfalls to that approach? The biggest one I can think of is that the instructor can't edit/fix those instructions if they're in a repo they don't control.

Thoughts?

[rgaiacs]

Then we can have an <iframe> that embeds setup.html instructions from each item in lessons into the workshop page.

I'm against use <iframe> for static content because is very easy to break the <iframe>.

If you want to have something like

lessons: ["swcarpentry/shell-novice", "swcarpentry/git-novice", "swcarpentry/python-inflammation"]

on the YAML header that is going to be used to populate the page with installation instructions without any server-side processing I will suggest to use a similar (client-side Javascript) approach that I took when implementing the all in one version of the lesson.

Client-side Javacript Proposal

User has

lessons: ["swcarpentry/shell-novice", "swcarpentry/git-novice", "swcarpentry/python-inflammation"]

on the YAML header of index.md. (GitHub Pages) Jekyll will build index.html from index.md and server the file to the user. User's web browser will load index.html and open a request to swcarpentry/shell-novice, swcarpentry/git-novice and swcarpentry/python-inflammation to recovery the installation instruction in HTML form. After the web browser receive the response for the installation instruction, it will select the instruction and inject them into the page.

Benefits

1. Standard workshop page easy to configure/setup.
2. We continue to use a GitHub Pages based workflow.
3. No server-side processing is required.
4. No HTML generation on user computer is require.

Drawbacks

1. Installation instructions should take a few extra seconds to load depending of the connection.
2. Customisation of the workshop page for non-standard tools will be hard.
3. Workshop website will not display installation instructions if lesson is broken.
4. Old web browsers or web browsers with Javascript disable will not be able to show the installation instructions.

[rgaiacs]

Please have a look at #459.

[fmichonneau]

partially implemented.