Use @scope to scope our Markdown rules

[delucis]

What version of starlight are you using?

0.37.1

What is your idea?

Switch to using @scope for limiting where our Markdown styles apply.

We can’t do this yet as browser support is not sufficient for us, but we should switch eventually.

Why is this feature necessary?

Starlight lets users opt out of Markdown styles using the not-content class. Currently we implement this using a :not(:where(.not-content *)) selector that looks like this in context:

starlight/packages/starlight/style/markdown.css

Lines 30 to 32 in 4b8171c

	.sl-markdown-content li:not(:where(.not-content *)) {
	overflow-wrap: anywhere;
	}

Except, sometimes it also gets a lot less simple 😬

starlight/packages/starlight/style/markdown.css

Lines 8 to 14 in 4b8171c

	/* 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);
	}

We should be able to refactor all these styles to be wrapped in a single @scope instead and simplify the code significantly. For example, styles can become a lot easier to reason about when the scoping logic is pulled up to an @scope block (which we’d need just once wrapping everything in our markdown.css file:

Before:

	.sl-markdown-content li + li:not(:where(.not-content *)),
	.sl-markdown-content dt + dt:not(:where(.not-content *)),
	.sl-markdown-content dt + dd:not(:where(.not-content *)),
	.sl-markdown-content dd + dd:not(:where(.not-content *)) {
		margin-top: 0.25rem;
	}

After:

	@scope (.sl-markdown-content > *) to (.not-content > *) {
		li + li,
		dt + dt,
		dt + dd,
		dd + dd {
			margin-top: 0.25rem;
		}
	}

Do you have examples of this feature in other projects?

Support only just landed in FF and this is an implementation detail, so not something users necessarily notice, but would make our maintenance lives simpler!

Participation

• I am willing to submit a pull request for this feature.