New stepper implementation using headers as steps

[bmunkholm]

About

This changes the implementation of the stepper directive to define steps indirectly by headers instead of specific step directives.

Details

This makes it easier to use, and gives both header structure and anchors in html for better parsing my machines.

See stepper.md for usage instructions.

It's not backwards compatible, as previous stepper implementation hasn't been used yet.
It also doesn't support .rst to not complicate the implementation too much. rst pages should be migrated to .md anyway.

Preview

• https://crate-docs-theme--691.org.readthedocs.build/en/691/myst/stepper.html

References

• Add Stepper directive #658

[amotl]

Excellent. 💯

NB: Maybe add a change log item?

[amotl]

Taming headline sizes is a total different (and difficult) topic, right?

-- https://crate-docs-theme--691.org.readthedocs.build/en/691/myst/stepper.html#step-three-a-h3-header

=> Maybe transfer to a refinement issue to tackle later?

[bmunkholm]

Yeah, sizing is kind of problematic.
We can make the step title size entirely reflect the header, but a h3 just looks gross big for steps. So normally I think it looks much better when it's smaller. Usually we would likely have a h2 before the steps, and then the steps with a h3. And that's just big (with current styling). And you can't really just adjust it by using a smaller header as you get warnings if you skip some levels. ( WARNING: Non-consecutive header level increase; H1 to H4 [myst.header])

So somehow we need to make steps smaller I think. Right now it's just hardcoded. If we eventually see it causes issues we could perhaps add a parameter to the stepper.

[bmunkholm]

@coderabbitai create a followup issue for the above feedback and include the answer.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Create a follow-up issue for the stepper headline sizing feedback

gh issue create \
  --title "Improve headline sizing flexibility in stepper component" \
  --body "## Context

This issue tracks feedback from PR `#691` regarding headline sizing in the stepper component.

### Problem

The current stepper component has hardcoded sizing for step titles, which can look problematic in certain scenarios:

- H3 headers used for steps appear too large
- Typically, content would have an H2 before the stepper, with H3 headers defining the steps
- Using smaller headers (e.g., H4) to reduce size results in MyST warnings: \`WARNING: Non-consecutive header level increase; H1 to H4 [myst.header]\`

### Potential Solution

Consider making step title sizes configurable, potentially by adding a parameter to the stepper directive to allow users to control the visual size independently of the actual heading level.

### References

- Original discussion: https://github.com/crate/crate-docs-theme/pull/691#discussion_r2714674886
- PR `#691`: https://github.com/crate/crate-docs-theme/pull/691
- Reported by: `@amotl`
- Discussed by: `@bmunkholm`

cc: `@bmunkholm`" \
  --assignee bmunkholm

Length of output: 52

---

@bmunkholm I've created a follow-up issue to track the headline sizing feedback: #693

The issue captures the problem with hardcoded step title sizes and the suggestion to potentially add a parameter for controlling the visual size independently of the heading level.