Space and indent embedded components inside lists

[enf0rc3]

Implements the Embedded component design.

Figma wraps every non-text block embedded in the body — image, callout, table, code block — in a slot with space/8 above and below, on top of the space/16 block gap, and indents it with the list when it sits inside one.

	Before	After
Space above/below an embedded component in a list	0px	24px
Space above/below a table	16px	24px
Space above/below an image in a list	40px	24px
Paragraphs stacked in a list item	0px	16px
Nested list under an item	0px	6px
Table cell padding	0px	16px / 24px
Copy button offset from its code block	24px	0px

Indentation is 24px at list level 1 and 48px at level 2, matching the design.

Verified on the preview

Measured in the browser, light and dark:

• Code blocks and a callout inside an ordered list — every block 24px clear of the text above it and indented to 24px, copy buttons flush with their code blocks.
• Images inside an ordered list — figures at 24px, down from 40px.
• Tables — cells padded 16px / 24px instead of 0, and the table sits 24px clear.

Bugs found along the way

• Table cells referenced --space-16 / --space-24 / --space-12. Those don't exist — the tokens are --space16 etc. — so every cell on every page with a markdown table rendered with no padding at all.
• The copy button lives in a zero-height div injected in front of each code block, so the block's own top margin pushed the block away from its button instead of away from the text above it.
• li:has(figure) spaced figures in list items with flex gap, which stacks with the margin instead of collapsing into it.

Checked, no change needed

The leading section (32px above the first paragraph, 56px above an h2, 12px below it, 16px between paragraphs) and the list (24px indent, no top padding on the first item, 6px between items) both already match main.

Out of scope: the code block header bar, which is #3317.

🤖 Generated with Claude Code

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3325.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[rosslovas]

I noticed this PR added numbers to some lists that weren't there before. Example (note the new 4.):

Production:

Your PR:

What's going on here, was this intentional? It wasn't called out in the "bugs found along the way" in the PR description, but looking at the markdown this seems like a fix to me, these numbers probably should've been visible all along 🤔

[borland]

@rosslovas @enf0rc3 Yeah, that's super weird about the list now showing 4 when it didn't before. Looking at the source markdown file, there's a 4 in it, so the intent of the author was obviously for a number to be visible. This PR fixes a bug rather than creates one.

Viewing source on both prod and the staging site, it's identical, both are simply

<li>
<p>Give the new Private Endpoint a name and either accept or customize the generated Network Interface Name. Click “Next”.</p>
<figure><p><img src="/docs/img/octopus-cloud/images/create-private-endpoint-basics.png" alt="An example of how to fill in the basics tab while creating a private endpoint in the Azure Portal"></p></figure>
</li>

a) Why didn't we previously see it?
b) How can CSS-only change affect this?

I asked claude and it says this

If the item after the broken one shows 4 (as you describe), the browser isn't counting that <li> as a list item at all. If it showed 5, the item is still a list item and the marker is merely not being painted.

Case A — the count skips (marker never generated)

An <li> only gets a marker and only increments the list-item counter while its computed display is list-item. Anything that overrides that — display: block, flow-root, flex, grid — silently removes both. This is a very common casualty of spacing fixes, because display: flow-root and overflow: hidden are the standard tricks for containing collapsing child margins, and docs stylesheets often apply them to list items that contain block children like your

.

So look for a selector that matches only the items containing a figure — something like li:has(figure), li > figure ~ *, or a rule keyed off the image wrapper. Check the fourth <li> in DevTools: computed display should read list-item. I'd also check item 6, which has the same structure — I suspect it's broken too and you just noticed the first one.

Using browser devtools, the other li's show a ::marker pseudo element but this one doesn't, and sure enough in the main.css we have

.page-content {
  /* Heading gaps rely on sibling margin collapsing, which only happens in block
     flow. Converting this to flex or grid makes every gap additive again -
     56px above an h2 becomes 72px after a paragraph, 88px after a blockquote. */
  display: flow-root;
  padding-block-start: var(--space32);

  li:has(figure) {
    display: flex;
    flex-direction: column;
    gap: 1rem;
  }
}

Which this PR has removed.

Nice fix. Approved