Steps

Steps present a numbered procedure. The content must be exactly one ordered list; items may hold nested blocks such as code or callouts. The list's start number is honored, so a procedure can continue from an earlier one.

If a list does not start at 1, leave a blank line after the opening fence: a stock CommonMark parser cannot start such a list directly after a paragraph line, and the validator warns when it would be swallowed.

Attributes

Steps take no attributes of their own beyond an id and classes. The numbering comes from the list.

Content must be exactly one ordered list. Items may hold any blocks, so a step can carry a code block, a table or a callout.

Downgrade: the list, unchanged.

Watch for: a list that does not start at 1 needs a blank line after the opening fence. Without one, a stock CommonMark parser cannot start a list with a different number directly after a paragraph line, and the numbering is lost in the fallback. The validator warns when that would happen.

Examples

Content must be exactly one ordered list. The numbering comes from the list, so the source reads as a procedure even unrendered.

:::steps
1. Install the CLI.
2. Run `markset init`.
3. Edit `markset.toml`.
:::

1. Install the CLI.
2. Run `markset init`.
3. Edit `markset.toml`.

A step can carry code, a table or a further list. This is the usual shape of a real procedure.

:::steps
1. a
   - x
2. b
:::

1. a
   - x
2. b

A list starting at 3 keeps its numbering, which is how a procedure continues across sections.

:::steps

3. a
4. b
:::

3. a
4. b

A card inside a step needs the outer fence to be longer, as everywhere else.

::::steps
1. a
   :::card
   x
   :::
::::

1. a

   x

What the validator catches

Every error below is specified; nothing degrades silently.

:::steps
:::

:::steps
- a
:::

:::steps
text
:::

All 13 cases for steps are in the conformance browser. The normative text is spec §4.