Experimental CLI reference pages render shortcode tags as a code block

[aheritier]

---

Description

Every CLI reference page where the command is marked experimental: true or experimentalcli: true renders an HTML fragment as a literal code block instead of the styled experimental notice.

Affected example: https://docs.docker.com/reference/cli/docker/pass/

The "Experimental" callout displays as:

</span>
<strong>Experimental</strong>

inside a grey code block, followed by the rest of the experimental copy as normal prose.

Thanks @scraly for reporting it

Affected pages

All 27 CLI pages with experimental: true or experimentalcli: true in data/cli/:

• docker pass, docker pass {set,get,ls,rm}
• docker scout {policy,environment,compare,stream,vex,vex get,attestation,attestation add,attestation get,attestation list}
• docker checkpoint {,create,ls,rm}
• docker manifest {,annotate,create,inspect,push,rm}
• docker buildx debug, docker buildx debug build

Root cause

layouts/cli.html renders the experimental notice by feeding a string containing the {{% experimental %}} shortcode through markdownify:

{{ if or $data.experimental $data.experimentalcli }}
  {{ markdownify `
{{% experimental %}}

**This command is experimental.**
…
{{% /experimental %}}`
  }}
{{ end }}

The shortcode template (layouts/_shortcodes/experimental.html) embeds the icon partial inside an indented <span>. Heroicons SVGs are pretty-printed:

<svg …>
  <path … />
</svg>

Once expanded into the shortcode's HTML and re-parsed as Markdown, the <path> line and the closing </span> / <strong>Experimental</strong> lines sit at ≥4-space indent — Markdown then treats them as an indented code block.

Regression

Introduced in commit ee71c80 — "chore: migrate icons from Material Symbols to Heroicons" (2026-05-13). The Material Symbols icons were single-line SVGs, so the same template code produced single-line indented HTML that Markdown left alone. The Heroicons SVGs are multi-line, which crosses the indented-code-block threshold inside markdownify. cc @dvdksn

Proposed fix

Replace the markdownify block in layouts/cli.html with the inline rendered HTML — no markdownify round-trip and no shortcode dependency for this code path. PR to follow.

---