tutorial
tutorial copied to clipboard
DjangoGirls
Open the system-specific dropdowns automatically
It's inconvenient that on each page the participants have to open the system-specific (e.g. Linux, Windows, OS X) dropdowns manually. Sometimes they forget about opening one of them, thus they fail to run a crucial command which breaks things later.
My recommendation: Add JavaScript to auto-detect the operating system used, and auto-open the system-specific dropdowns.
My additional recommendation: Add buttons (links) to open all all dropdowns for a specific system. This should apply to all pages of the tutorial.
My additional recommendation: If the user manually opens a dropdown, all other dropdowns with the same system should auto-open, or there should be a link displayed which can be used to open all of them.
I wholeheartedly agree with this. In the team I coached, people scrolled over multiple important command boxes because they forgot to click them open.
Is that possible on GitBook; or if not, would GitBook consider such a feature request?
If not, maybe we could simply generate separate tutorial variants for different systems (with all content for the respective platform visible without any dropdowns) from common source documents? This might require us to develop some continuous integration of our own, in addition to or as a replacement of the one provided by GitBook.
I guess it would at least involve some Javascript trickery to detect the OS, and I don't see a way to do that in the current GitBook framework.
If we want to go with the generate-several-static-variants-from-a-single-source approach, Asciidoctor supports that quite well with attributes you can set on the command line and use as conditionals within the documents. I'm using that for OpenSchoolMaps to generate worksheets with and without solutions. Here's where the attribute is set in the build script and here is one of the many places where it's used to control whether content should be displayed or not. The whole build (and automatic deployment on success) is fully automated through GitLab's CI/CD feature and hosted on GitLab pages, so once set up, this would offer a similar level of comfort as we have today with GitHub + GitBook: Check in a change and some minutes later the online content is up-to-date with that.
This would require the source documents to use AsciiDoc as markup language instead of MarkDown, though, and I don't know how well that integrates with CrowdIn for the translations.
With MarkDown as source, something similar can be achieved by using Pandoc and custom pandoc filters. Or of course one can come up with a preprocessing of their own and feed the result into an existing pipeline, maybe even still GitBook.
I think a GitBook plugin would be the best route. It would have to produce the JS/CSS necessary for this functionality. Generating several static output versions seems like it would add a lot of complexity in the production, translation and usage of the tutorial.
Several GitBook plugins are already used by the tutorial, they are specified in book.json And there are many plugins at https://plugins.gitbook.com/browse but last time I looked none that would do exactly what we want. The existing "sectionx" plugin is what makes the collapsing sections, so it might be a starting point for custom development of a new plugin, for example adding Windows | Mac | Linux | etc toggle buttons for a single section. And then use JS to detect, and remember the OS setting, etc.
Oh actually I forgot there is a better gitbook plugin to consider using and enhancing: simpletabs And there's even a PR for adding it to the tutorial at #1173, although as noted there it would require further updates to be ready to go