Fix Astro Island margins in Markdown

.changeset/wicked-meals-return.md

@@ -0,0 +1,14 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds missing vertical spacing between Markdown content and UI Framework components using [client directives](https://docs.astro.build/en/reference/directives-reference/#client-directives).
+
+**⚠️ Potentially breaking change:** By default, Starlight applies some vertical spacing (`--sl-content-gap-y`) between Markdown content blocks. This change introduces similar spacing between Markdown content blocks and UI Framework components using client directives which was not present before.
+
+If you were relying on the previous behavior, you can manually override the spacing by manually specifying the top margin on the component using [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles), e.g. by relying on a CSS class to target the component.
+
+```css
+.my-custom-component {
+  margin-top: 0;
+}

packages/starlight/style/markdown.css

@@ -2,7 +2,15 @@
 	.sl-markdown-content
 		:not(a, strong, em, del, span, input, code, br)
 		+ :not(a, strong, em, del, span, input, code, br, :where(.not-content *)) {
-		margin-top: 1rem;
+		margin-top: var(--sl-content-gap-y);
+	}
+
+	/* Vertical spacing between Markdown content blocks and UI Framework components using client directives. */
+	.sl-markdown-content
+		:not(a, strong, em, del, span, input, code, br)
+		+ :is(astro-island, astro-slot)
+		> :not(a, strong, em, del, span, input, code, br, :where(.not-content *)):first-child {
+		margin-top: var(--sl-content-gap-y);
 	}
 
 	/* Headings after non-headings have more spacing. */

packages/starlight/style/props.css

@@ -101,6 +101,7 @@
 		--sl-sidebar-pad-x: 1rem;
 		--sl-content-width: 45rem;
 		--sl-content-pad-x: 1rem;
+		--sl-content-gap-y: 1rem;
 		--sl-main-pad: 0 0 3vh 0;
 		--sl-menu-button-size: 2rem;
 		--sl-nav-gap: var(--sl-content-pad-x);