Pagination for some step by step tutorials, not all

[jensbri]

Kia ora.

I would like to have some step-by-step instructions included in my documentation. Based on the idea not to overwhelm the reader with a wall of text. So break it down into pages/individual markdown files---paginate it.

I have experimented with the
- navigation.footer
option but that gives me a very crude implementation where backwards and forwards isn't really controllable. I can't just have one 7 step guide with back and forward buttons, but it would go backwards to any previous page.

There might be an option to use it as a blog. But that seems a bit like overkill.

I'd ideally also want to include some Bootstrap.

Thanks for sharing suggestions.

Cheers
J

[alexvoss]

Kia ora,

I am wondering about the same thing. In many learning management systems there is a main navigation and then a navigation through a set of units, steps, activities, etc. that make up a learning sequence. Often, there are buttons at the top of the page that represent each one of these and show the learner's progress through the sequence.

Now, with Material, I would utilize the table of contents to provide the navigation. In keeping with the aim to not overwhelm the learner and to focus their attention, I would hide all content that is not in a currently selected part. That means adding some JavaScript to the ToC to hide/unhide the parts.

Of course, with this setup, the navigation.footer feature would take the learner to the next / previous learning sequence instead of the next / previous part. That would either need to be changed or a separate mechanism for navigating within the learning sequence would need to be added.

Does that approach sound like what you had in mind?

Re including bootstrap, there has been a previous discussion #2461 but that was quite a while back. I do wonder what would happen today? I don't really know Bootstrap well enough to judge what issues might arise but perhaps others have experience?

[squidfunk]

I'm happy to iterate on a recipe for creating such tutorials (as part of our examples initiative), and if we can improve the situation, we can consider adding further custom components. However, we definitely should try to keep it as generic as possible.

[alexvoss]

The solution you suggested works well for stand-alone tutorials and I think this should always be an option to consider. However, when embedding a tutorial inside a wider existing site then the choice of navigation options may be fixed. I am also looking at an example tutorial from the software carpentry and I find it overwhelming as there is no sense of a chunking of effort, just one long navigation. That navigation scrolls out of view quickly and so does not give the learner a sense of progress. As @jensbri said, that is something to avoid. (edit: Material would do a better job by default with regard to losing the navigation from view.)

[jensbri]

Kia ora.

I feel this discussion is really fruitful!
Thank you guys!

As @alexvoss has mentioned The Carpentries, I will throw another one in the mix:

The Nectar Research Cloud (Australia/NZ).
I highly appreciate their tutorials.
Let's have a look:

• There is an overview with tiles (I don't see an immediate need for that for my use-case, but it's a nice idea)
• Once you are in one tutorial, you get a lot of relevant information (and almost all screen estate is dedicated to this one tutorial
  • What series the tutorial in question is part of
  • box on the left with CATEGORY, DIFFICULTY, DURATION (I really like this one).
    • Containing this information in the md header is in my opinion the way to go
    • the SVG is also neatly done
  • the ToC on the left highlighting which step we are currently looking at (yes, percentage might be another option with pros/cons)
  • PREVIOUS/NEXT buttons on the top. I am not a fan of the completely different look of the 'Next' in the bottom/MKDocs-Footer-like area

Please note, that they currently don't have a license, we can't just copy.
Cheers,
J

[jensbri]

Update. The Nectar documentation now has a license.

[alexvoss]

I just stumbled across this previous discussion - #4433 - which might help produce the desired effect. It might be an idea to think about an option for the navigation.footer feature that makes this configurable. Not sure what the setting and behaviour would need to be, though. One option would be to control whether the previous / next links are shown with metadata in the page header. That would seem the most generic solution to me.

[jensbri]

Kia ora.

I am wondering if the button solution mentioned above enhanced with some code and a order variable as part of the yml header of each *.md file would be a generic-enough option. Another binary variable click-tutorial would help.

The idea is:

• yhl header: click-tutorial: yes gives us a switch to see if we even have to worry about the following things
• yhl header: order gives us a sequence number, yes, that's manual and can be conflicting, but it seems to work for Nectar
• code to count all vs. the highest order (to also gives us a Step 1 out of 13 progress bar_
• if statement(s):
  • if click-tutorial: yes && order=1 do not show a 'previous' button
  • if click-tutorial: yes && order=highest do not show a 'next' button
  • if click-tutorial: yes && order!=1&&!=highest go through the folder and find the next increment in order number, put this as a link for the next button

Implementation

• Option a: [could in theory be done with Snippets that are well integrated with MKDocs Material
• Option b: Python
• Option c: probably best to be done with JavaScript? But I am not familiar with that.
  Cheers
  J

[jensbri]

in addition to that, the front matter/yml creation can probably be further simplified by using the built-in meta plugin

[jensbri]

Update: exploring more of the Snowflake documentation, I have stumbled upon Google Codelabs.
There is already an approach to integrate these into MKDocs Material. But my crude attempt of removing all specific version requirements to that have broken it.
My dear colleague has helped me in fixing this, leading to this Merge Request.
Now I have very neat clickable instructions that live within the mkdocs material site, are paginated and so many other cool things, I highly recommend having a look if you are searching for a similar solution.

[alexvoss]

That does look interesting. In the meanwhile, I have expanded the tutorial on writing tutorials using Material for MkDocs that I had been working on. I am looking for some feedback on this, so invited you to it. I am not entirely sure where this exercise will go. At the moment it is not public but in one form or another, I think it should be exposed to the light of day soon.