New list type: Steps

[ofek]

Context

https://squidfunk.github.io/mkdocs-material/reference/lists/

Description

It would be nice to have a dedicated way to display list items that represent steps the user must follow to achieve a particular task.

Related links

• https://mintlify.com/docs/content/components/steps
• https://starlight.astro.build/components/steps/

Use Cases

A user must follow directions to achieve a desired outcome like the installation of a program.

Visuals

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting! We already have this on our list, and we'll revisit this once we got our current efforts sorted out ☺️

[A3Bagged]

I've actually came up with a markdown extension for this.
i was looking for the same thing.

I don't know python well so code could be improved but i've done my best and it works.
I've included it on my ci.yml with pip install stepslist so that i can use it online.

Link to repo

I've tried making it with <steps> & </steps> tags but after 2 days of tinkering i found out that markdown or mkdocs closes any open html tags so it would actually output as:

<p><steps></steps></p>
<ol>
<li>

etc..

for further info take a look at #7775

Changing to using --steps-- & --!steps-- has allowed me to do this.

These can then be styled with css using the class name .md-steps and ::before ::after pseudo elements to have something like your example.

Mine currently look like this

[squidfunk]

Looks great, thanks for sharing!

[facelessuser]

I kind of liked the "steps" idea, so I figured I'd post this. I didn't bother with a specialized "steps" extension or using custom tags and just utilized existing wrapping approaches and standard tags. I provided the necessary CSS so people could mimic this if they'd like. The colors can be overridden with whatever if something else is preferred. It should work with the default light and dark theme.

:root > * {
	 --md-steps-bg-color: var(--md-code-bg-color);
	 --md-steps-fg-color: var(--md-code-fg-color);
	 --md-steps-border-color: hsla(0, 0%, 75%, 1);
}

:root > *[data-md-color-scheme="slate"] {
	 --md-steps-border-color: hsla(225, 15%, 30%, 1);
}

.md-typeset div.steps > ol {
	 counter-reset: item;
}

.md-typeset div.steps > ol li {
	 position: relative;
	 padding-left: 1em;
	 list-style: none;
}

.md-typeset div.steps > ol li::before {
	 position: absolute;
	 top: 0;
	 left: 0;
	 z-index: -1;
	 display: block;
	 width: 1.75em;
	 height: 1.75em;
	 margin-left: -1.25em;
	 color: var(--md-steps-fg-color);
	 font-weight: 600;
	 font-size: 0.9em;
	 text-align: center;
	 background-color: var(--md-steps-bg-color);
	 border: 1px solid var(--md-steps-border-color);
	 border-radius: 100px;
	 content: counter(item);
	 counter-increment: item;
}

.md-typeset div.steps > ol li::after {
	 position: absolute;
	 top: 0;
	 bottom: 0;
	 left: -0.36em;
	 display: block;
	 width: 1px;
	 margin-top: 2em;
	 border-left: 1px solid var(--md-steps-border-color);
	 content: '';
}
 

[squidfunk]

Nice, thanks for sharing! What we envision is that this works without "Yet Another Markdown Syntax Extension", and in this case, it does by just wrapping it with a div. However, in the future we want to provide options to have more involved components that are easy to use, encapsulating an arbitrary amount of business and rendering logic. This is why we are not going to rush this, but take it back to the drawing board.

We already have some solid concepts that generalize well, but first need to finish our current foundational work.

[A3Bagged]

@facelessuser looks good! Wrapping it inside a class “steps” is alot easier (though the reason why i did the extension is the people that write the docu arent familiar with html)

[facelessuser]

@A3Bagged I'm not criticizing the use of an extension, just decided to post a solution for those that are okay using existing availability. I likely won't use a specialized extension, but I understand that some may prefer such. The CSS can easily be modified to work with custom tags as well.