WIP - Tutorial

[fflaten]

Introduces a new tutorial section where users can follow along from creating a module to have it fully tested including code coverage.

• Adds a separate docs plugin instance for Tutorial
  • To avoid versioning
  • To simplify customizations
• Replaces the table of contents component with a progress tracker when in the Tutorial plugin. Progress is stored in the user's browser based when they complete the checklist at the end of each page.
  • Very inspired by Astro's docs.
• Hides version dropdown from homepage/index and Tutorial section where it's irrelevant. Tutorial is not versioned and homepage has hardcoded links to latest quick start + installation guide.
• Content is first draft and mostly AI-generated.
  • Looking for input on what to cover, in which order etc. 🤖

Other changes:

• Added support for diff-highlighting to codeblocks using comments.
• Updated navbar styling and sidebar to make it easier to users to see understand if they're in Docs, Commands vs Tutorial
• Moved Command Reference to separate sidebar so "Commands"-link in navbar becomes active - and to reduce sidebar length for Docs. Also applied to v4 and v5
• Updated links on main page to respect the users chosen version. Fixed weird behavior when user had changed version and then navigated between index -> quick start (force v6) -> tutorial (neutral) -> Docs/Commands in navbar (back to previous user selection)
• Minor changes in latest docs for typo and broken

[fflaten]

Not sure why CI is failing. "Host key verification failed" error in Netlify often caused by submodules which is not used AFAIK.

Edit: Looks like a intermittent issue in Netlify or Github. Another report on Netlify forums now.

[bravo-kernel]

Super nice 😍

[nohwnd]

This is amazing work :)

All the content looks amazingly structured. Only place where I "struggled" was having hard time telling if I am in docs, or in tutorial after clicking the tutorial link:

I see the tutorial progress on the right, but maybe it could say Pester - Tutorial in the blue section as well?

[fflaten]

Thanks! Yeah, I've wanted to create this for a while since discovering the amazing docs for Astro. Think it turned out well, matching our style.

Navigation
Would you prefer a "Back to Docs" button next to the Pester-logo in the navbar, or simply having a active style on the Docs/Commands/Tutorial button top right like Docusaurus? Or both?

IIRC we removed the default active style because the Comands button links to Docs which looked weird. However, now that we have many Should-* I was going to suggest splitting Commands into a separate sidebar anyways like maester.dev. Thoughts?

Content
What about the module structure (ignore the text for now)? I want this to evolve naturally, so which topics should be covered and when? Missing at least BeforeDiscovery. Maybe passing data between Discovery -> Run as an advanced data-driven module later. More?

The simple Planet-module is a bit limiting, but used it for consistency and cross-platform support. Keep or create something new?

[nohwnd]

navigation: I would have to see it to tell.

content: I liked that the module stayed on topic, imho we should merge and let people try it out rather than guessing what would make it better.

[bravo-kernel]

I think it does indeed look a little bit too much like the documentation site.

Perhaps changing Introduction to Tutorial would help.

[fflaten]

See latest experiment. Better?

• Extracted Commands to own sidebar, so navbar links at top can have working active style
• Added a static category as a sidebar header. Don't like how it looks vs a static header (see below), but it's included in the breadcrumbs which is kinda nice.
  • Might be easier to just rename "Introduction" module in tutorial to something unique (below)

Perhaps changing Introduction to Tutorial would help.

That's also the module name used in the tracker so don't want it too generic, but "Tutorial basics" or something could work if we need it. 🙂

Would you prefer a "Back to Docs" button next to the Pester-logo in the navbar

Example with button + a static sidebar header. Didn't like it personally. You have the Docs-button next on the navbar anyways and it's currently invisible on mobile (would get cluttered).

We could also just switch places between Docs/Commands/Tutorial and the version dropdown, like default template. Then the sidebar name is right in your face.

[bravo-kernel]

I think this is already strong. The wording "Exit Tutorial" might make it more clear though.

[fflaten]

I think this is already strong. The wording "Exit Tutorial" might make it more clear though.

I assume this was the button. Went a different direction, see latest preview. Does that work? Breadcrumbs mentioning the root category (sidebar name basically) and clear highlighting of the active sidebar (on desktop).

Extended with a new module for test organizing etc. Claude is getting both verbose (to answer my comments) and forgets other agreements, so need help cleaning it up 😄 And making sure it all works and makes sense with fresh eyes. If someone could help me demo it that would be great. Will try myself tomorrow.