Plugins Steps

lay out a page @mdsvex/plugin-steps@0.1.0-next.1

Steps

Numbered steps, each heading inside a steps directive starts one

Install

pnpm add -D @mdsvex/plugin-steps@next

Turn it on

import { steps } from '@mdsvex/plugin-steps';

mdsvex({ plugins: [steps()] });

What it reads

:::steps :::step[Title]

owns steps, step

An example

You write
:::steps

## Install

Add the package.

## Configure

Put it in `plugins`.

:::

You get
  1. Install

    Add the package.

  2. Configure

    Put it in plugins.

Build-time preview.

Each heading written directly inside :::steps starts a step. The heading is its title, and what follows, up to the next such heading, is its body:

:::steps

## Install

```sh
pnpm add mdsvex@next
```

## Configure

Add it to the config.

:::
<ol class="steps" role="list">
	<li class="step">
		<div class="step-title"><h2>Install</h2></div>
		<div class="step-body"><pre>...</pre></div>
	</li>
	<li class="step">
		<div class="step-title"><h2>Configure</h2></div>
		<div class="step-body"><p>Add it to the config.</p></div>
	</li>
</ol>
  • The first heading sets the depth. If it is a ##, every ## written directly inside the container starts a step. A heading of any other depth is content of the step it is in.
  • (level=3) names the depth instead, as in :::steps(level=3), whatever the first heading is.
  • Only headings written directly inside count. One in a block quote, a list or another directive starts no step.
  • Content before the first heading is in no step. It stays at the top of the list, where only list items belong, so put an introduction above the container or in its brackets: :::steps[Set up a project] renders that text in a <p class="steps-label"> ahead of the list.
  • Steps nest when the outer container uses more colons, and the inner list counts from 1.
  • A step can be written out as :::step[Its title] inside the container, beside the ones headings make.

The titles are still headings, so heading_ids and anchors reach them.

The numbers are drawn by a small stylesheet that comes with the components, from a CSS counter. Its selectors have no specificity, so any rule of yours wins, and it reads these custom properties from .steps:

propertydefault
--steps-marker-size1.75rem
--steps-gap0.75rem
--steps-marker-colorinherit
--steps-marker-backgroundthe text colour at 12%
--steps-linethe text colour at 20%

steps({ css: false }) leaves the stylesheet out and keeps the markup, which is then a plain numbered list. Write your own from there, or start from a copy of @mdsvex/plugin-steps/steps.css.

To change the markup, export your own steps or step from a directives module. It replaces the plugin's component and gets the same props, label (the title, or the bracket text of the container) and children:

src/lib/Step.svelte
<script>
	let { label, children } = $props();
</script>

<li class="step">
	<header>{@render label?.()}</header>
	{@render children?.()}
</li>
src/lib/directives.js
export { default as step } from './Step.svelte';

The plugin's own components can be imported from @mdsvex/plugin-steps/Steps.svelte and @mdsvex/plugin-steps/Step.svelte, to wrap one in yours.

Options, from its types 1

css?: boolean
False leaves the default stylesheet out, the markup and its class names stay the same

Components @mdsvex/plugin-steps/Steps.svelte, @mdsvex/plugin-steps/Step.svelte

Stylesheet @mdsvex/plugin-steps/steps.css, or steps({ css: false }) for none

Find another plugin · Write your own

mdsvex, markdown with Svelte in it. MIT licence.