Skip to main content

Markdown Capabilities

Steps

An ordered, numbered tutorial container — and the colon-nesting rule that silently drops your content if you get it wrong.

Pipeline A does not support steps. ::::steps inside an AUP format: "markdown" text field renders as literal text. This container is pipeline-B only, and (362 files) the third most-used extension in a real production corpus.

The colon-nesting rule — read this before writing a steps block

remark-directive uses colon count to decide leaf vs. container, not just fence matching: exactly 2 colons (::name) is always a leaf directive — it can never have a body, no matter what follows it on later lines. 3 or more colons (:::name … :::) is a container directive — it can hold block children (paragraphs, lists, code, even a nested admonition). step needs a body, so it must use 3 colons, never 2; the wrapping steps container then needs one more than that (4), so its own closing fence can't be confused with an inner step's:

markdown
::::steps
:::step{title="First step"}
...
:::
::::

Get the colon count on step wrong and the ENTIRE step silently disappears — not just its body, the title too — no error, no warning. This was verified empirically against this exact pipeline, not assumed: writing step with only 2 colons (a leaf directive, thinking "2 is probably enough") makes content-reader.ts's stepsDirectiveToAup() skip it entirely, because a leaf directive's parsed type (leafDirective) never matches the containerDirective check that function requires:

markdown
::::steps
::step{title="This step silently disappears entirely"}
This text never reaches the page — no error is raised anywhere, and neither is
the title above.
::::

Rendered, the container above produces an empty, item-less step list — nothing at all, not even a placeholder. (Using the SAME colon count for both the outer steps and the inner step, e.g. 3 and 3, does NOT lose content in this parser — it renders the step correctly and merely leaves one stray, harmless line of literal ::: text after it. The dangerous mistake is specifically dropping step down to 2 colons, turning it into a leaf.)

The fix: anything that needs a body must use 3+ colons, never 2 — and the wrapping container should use one more than its deepest nested container, so card-group wrapping action-card (3 colons) uses 4, matching steps/step above; a directive that never needs a body (like action, 2 colons) is fine as a leaf. See Cards for the card-family example.

A working example

Source:

markdown
::::steps
:::step{title="Install the CLI"}
Run `npm install -g arc-cli` to get started.
:::

:::step{title="Configure your project"}
Create an `arc.config.json` file with your settings.

- Set your DID Space endpoint
- Set your default locale
:::

:::step{title="Deploy"}
```bash
arc space diff --server https://staging.example.com
arc space deploy --server https://staging.example.com
```
:::
::::

Rendered:

  1. Install the CLI

    Run npm install -g arc-cli to get started.

  2. Configure your project

    Create an arc.config.json file with your settings.

    • Set your DID Space endpoint
    • Set your default locale

  3. Deploy

    bash
    arc space diff --server https://staging.example.com
arc space deploy --server https://staging.example.com

Each step's body accepts any block content — text, a list, a code block, even a nested admonition — via the same recursive conversion the rest of this pipeline uses. A step with no title still renders (as an untitled numbered item); the numbering itself comes from a native <ol>, so assistive tech announces "step N of M" without the title needing to repeat it.