Fix Astro Island margins in Markdown #3340

HiDeoo · 2025-07-25T08:16:06Z

Description

Closes No margin between Markdown content and UI framework components #3290

This PR attempts to fix an issue where Starlight's Markdown default margins are not applied when using interactive UI frameworks components (Astro Islands).

I don't think we can really reuse our existing rule for this and we may need to have a special case targetting the first child of an island. This PR temporarily adds a few test scenarios to the /getting-started/ page and I'll also play around with more to see if there are other edge cases we might need to consider.

changeset-bot · 2025-07-25T08:16:10Z

🦋 Changeset detected

Latest commit: 67ddf34

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2025-07-25T08:16:11Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`67ddf34`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/68adb0e554f8c40008fe5452
😎 Deploy Preview	https://deploy-preview-3340--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2025-07-25T08:16:39Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	getting-started.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

delucis

Thanks for getting the ball rolling on this one @HiDeoo!

Do you have any more tests that you think we need for confidence? With more realistic scenarios?

In the abstract, this looks OK, but I find it a bit hard to predict what the real-world island usage will actually look like. Especially for slotted content.

I will note that given the additional styles, extracting the margin to a custom property might be a good idea. Would make it a bit easier for people to tweak spacing rather than needing to override all the various margin styles we’ll end up with.

delucis · 2025-07-25T14:14:45Z

@KianNH shared this page and island: https://developers.cloudflare.com/ai-gateway/demos/

Source: https://github.com/cloudflare/cloudflare-docs/blob/production/src/content/docs/ai-gateway/demos.mdx?plain=1

HiDeoo · 2025-07-25T17:45:53Z

Do you have any more tests that you think we need for confidence? With more realistic scenarios?

Definitely 👍 That's what I meant in the PR body and I plan on doing that this week-end. I want to try with some random components I use in various projects and test various scenarios, and see if I can find any issues.

Thanks for linking the Cloudflare example, I'll have to test against it too as I mostly worked on relatively simple components so far. I'll undraft the PR once I have done that and feel more confident about the changes.

Regarding the refactor, totally agree, right now I just added new rules and did not even try to see if some smarter refactors could be done or not.

trueberryless · 2025-07-25T19:37:17Z

Thanks @HiDeoo for picking up this issue and investigating on even better improvements 🙌

Also big thanks for @delucis and @KianNH for sharing knowledge too. Awesome! 🤩

HiDeoo · 2025-07-29T09:14:29Z

Added a few more examples, but turns out after checking, I'm not a heavy island user and even less in the middle of content, most of the time it would be in layouts or just Astro components 😅

I added one matching the Cloudflare example, a few others that came to mind, but in the end, I still feel like I may not have a full grasp of all or most common use cases of islands in the middle of content.

I'll try exploring something like https://github.com/search?q=language%3Amdx+%22client%3Aonly%22&type=code&p=1

HiDeoo · 2025-08-19T14:12:58Z

As mentioned, I've been trying more examples based on searches like https://github.com/search?q=language%3Amdx+%22client%3Aonly%22&type=code&p=1 and a few others. So far, every examples behaved as expected using the new changes from this PR but I'm still not super confident about the change considering I'm not a heavy island user, even more in the middle of content.

I'm opening up this PR for review in case it can bring more awareness to the change and get more feedback from the community if some users are running into similar setups and can to test it out. I will only move forward with the suggested refactoring if we decide to ship this change.

delucis

I’m personally pretty happy with the proposal and the thoroughness of the testing we’ve done — after all the PR is currently 3 lines of genuine CSS additions, and more than 1,000 lines of testing 😁

I think we could release it and see if we get more feedback.

Do you think it should be a minor given the changes? Or do we think it’s safe enough for a patch? People will either get improved spacing OR if they already did something to remediate it nothing should change (their custom CSS wins or they have wrapper elements which are not impacted by this change).

HiDeoo · 2025-08-20T13:17:16Z

Do you think it should be a minor given the changes? Or do we think it’s safe enough for a patch? People will either get improved spacing OR if they already did something to remediate it nothing should change (their custom CSS wins or they have wrapper elements which are not impacted by this change).

I'm a bit afraid of the opposite case where someone was relying on the previous behavior for some reason and do not want the margin, so I'm leaning towards a minor and including in the changelog some code to get back the previous behavior.

delucis · 2025-08-22T17:46:16Z

I'm leaning towards a minor and including in the changelog some code to get back the previous behavior

Sure — gives us a bit more space to document the change like you say 👍

* main: (55 commits) i18n(de): translate `themes.mdx` (withastro#3397) [ci] format i18n(ko): translate `themes.mdx` (withastro#3398) [ci] format docs: add Starlight Page to themes showcase (withastro#3393) i18n(de): update German themes (withastro#3394) docs: change image of Starlight Galaxy Theme dark image to not include a visible scrollbar (withastro#3395) [ci] format i18n(ko-KR): update `themes.mdx` (withastro#3392) [ci] format Add link to new Starlight theme (withastro#3390) i18n(fr): update `guides/css-and-tailwind.mdx` (withastro#3389) i18n(de): translate `guides/css-and-tailwind.mdx` (withastro#3386) [ci] format i18n(ko-KR): update `css-and-tailwind.mdx` (withastro#3388) Adds OmniPrint documentation to the showcase (withastro#3387) docs(showcase): Add Aptos Docs (withastro#3385) docs: add section about multiple Tailwind configs (withastro#3273) Add basic ESLint config, lint script and lint CI job (withastro#1640) chore(deps): update actions/checkout action to v5 (withastro#3375) ...

HiDeoo · 2025-08-26T13:14:35Z

Updated and cleaned up the PR.

I introduced a new CSS custom property as suggested (open on suggestions regarding the naming, e.g. what it represents vs. what it does). I also decided against merging the 2 rules into one, I think it hurts readability too much.

delucis

Looks good to me — and the variable naming seems spot on 🎯

trueberryless · 2025-08-28T20:54:21Z

Thanks HiDeoo for the awesome update 🙌

Since we re-use styles from Starlight, we need to set the new `--sl-content-gap-y` variable. See this PR for more context: withastro/starlight#3340

* Bump the npm group with 5 updates Bumps the npm group with 5 updates: | Package | From | To | | --- | --- | --- | | [@astrojs/sitemap](https://github.com/withastro/astro/tree/HEAD/packages/integrations/sitemap) | `3.5.1` | `3.6.0` | | [@astrojs/starlight](https://github.com/withastro/starlight/tree/HEAD/packages/starlight) | `0.35.2` | `0.36.0` | | [astro](https://github.com/withastro/astro/tree/HEAD/packages/astro) | `5.13.7` | `5.13.9` | | [sharp](https://github.com/lovell/sharp) | `0.34.3` | `0.34.4` | | [@tailwindcss/typography](https://github.com/tailwindlabs/tailwindcss-typography) | `0.5.16` | `0.5.18` | Updates `@astrojs/sitemap` from 3.5.1 to 3.6.0 - [Release notes](https://github.com/withastro/astro/releases) - [Changelog](https://github.com/withastro/astro/blob/main/packages/integrations/sitemap/CHANGELOG.md) - [Commits](https://github.com/withastro/astro/commits/@astrojs/[email protected]/packages/integrations/sitemap) Updates `@astrojs/starlight` from 0.35.2 to 0.36.0 - [Release notes](https://github.com/withastro/starlight/releases) - [Changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md) - [Commits](https://github.com/withastro/starlight/commits/@astrojs/[email protected]/packages/starlight) Updates `astro` from 5.13.7 to 5.13.9 - [Release notes](https://github.com/withastro/astro/releases) - [Changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) - [Commits](https://github.com/withastro/astro/commits/[email protected]/packages/astro) Updates `sharp` from 0.34.3 to 0.34.4 - [Release notes](https://github.com/lovell/sharp/releases) - [Commits](lovell/sharp@v0.34.3...v0.34.4) Updates `@tailwindcss/typography` from 0.5.16 to 0.5.18 - [Release notes](https://github.com/tailwindlabs/tailwindcss-typography/releases) - [Changelog](https://github.com/tailwindlabs/tailwindcss-typography/blob/main/CHANGELOG.md) - [Commits](tailwindlabs/tailwindcss-typography@v0.5.16...v0.5.18) --- updated-dependencies: - dependency-name: "@astrojs/sitemap" dependency-version: 3.6.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: npm - dependency-name: "@astrojs/starlight" dependency-version: 0.36.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: npm - dependency-name: astro dependency-version: 5.13.9 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: npm - dependency-name: sharp dependency-version: 0.34.4 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: npm - dependency-name: "@tailwindcss/typography" dependency-version: 0.5.18 dependency-type: direct:development update-type: version-update:semver-patch dependency-group: npm ... Signed-off-by: dependabot[bot] <[email protected]> * Fix content margin for non-Starlight pages Since we re-use styles from Starlight, we need to set the new `--sl-content-gap-y` variable. See this PR for more context: withastro/starlight#3340 --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Kyle Lacy <[email protected]>

* main: (26 commits) i18n(ja): resources/themes (withastro#3442) add openstatus showcase (withastro#3436) [ci] release (withastro#3434) Add `head` config validation for `meta` tags with `content` (withastro#3380) Fix Astro Island margins in Markdown (withastro#3340) Ensure tab links span the full tab height (withastro#3427) Move `<summary>` to top of `<details>` for validity (withastro#3423) Run all tests on CI workflow changes (withastro#3433) [ci] format i18n(fr): small rewording and fixes in top-level pages (withastro#3432) i18n(fr): small rewording and fixes in `guides` (withastro#3431) i18n(fr): fix typo and links in `reference` files (withastro#3429) i18n(fr): small rewording in `components` (withastro#3430) [ci] release (withastro#3384) i18n(de): Update `page.lastUpdated` translation to be more in‐line with the English translation (withastro#3416) Remove invalid value attribute from `<select>` (withastro#3421) Convert invalid `<div>` child of `<summary>` to `<span>` (withastro#3422) [i18nIgnore] Fix typo in Spanish docs documentation (withastro#3408) chore(deps): update actions/labeler action to v6.0.1 (withastro#3407) [i18nIgnore] Fix duplicate i18n collection definition (withastro#3409) ...

* main: (72 commits) Showcase: Add Saucer (withastro#3454) i18n(ja): resources/themes (withastro#3442) add openstatus showcase (withastro#3436) [ci] release (withastro#3434) Add `head` config validation for `meta` tags with `content` (withastro#3380) Fix Astro Island margins in Markdown (withastro#3340) Ensure tab links span the full tab height (withastro#3427) Move `<summary>` to top of `<details>` for validity (withastro#3423) Run all tests on CI workflow changes (withastro#3433) [ci] format i18n(fr): small rewording and fixes in top-level pages (withastro#3432) i18n(fr): small rewording and fixes in `guides` (withastro#3431) i18n(fr): fix typo and links in `reference` files (withastro#3429) i18n(fr): small rewording in `components` (withastro#3430) [ci] release (withastro#3384) i18n(de): Update `page.lastUpdated` translation to be more in‐line with the English translation (withastro#3416) Remove invalid value attribute from `<select>` (withastro#3421) Convert invalid `<div>` child of `<summary>` to `<span>` (withastro#3422) [i18nIgnore] Fix typo in Spanish docs documentation (withastro#3408) chore(deps): update actions/labeler action to v6.0.1 (withastro#3407) ...

* main: (87 commits) i18n(ja): sync outdated aside page (withastro#3465) i18n(ja): sync outdated icon reference (withastro#3467) chore(deps): update pnpm/action-setup action to v4.2.0 (withastro#3460) Showcase: Add Saucer (withastro#3454) i18n(ja): resources/themes (withastro#3442) add openstatus showcase (withastro#3436) [ci] release (withastro#3434) Add `head` config validation for `meta` tags with `content` (withastro#3380) Fix Astro Island margins in Markdown (withastro#3340) Ensure tab links span the full tab height (withastro#3427) Move `<summary>` to top of `<details>` for validity (withastro#3423) Run all tests on CI workflow changes (withastro#3433) [ci] format i18n(fr): small rewording and fixes in top-level pages (withastro#3432) i18n(fr): small rewording and fixes in `guides` (withastro#3431) i18n(fr): fix typo and links in `reference` files (withastro#3429) i18n(fr): small rewording in `components` (withastro#3430) [ci] release (withastro#3384) i18n(de): Update `page.lastUpdated` translation to be more in‐line with the English translation (withastro#3416) Remove invalid value attribute from `<select>` (withastro#3421) ...

fix: markdown island margins

28fd24a

github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Jul 25, 2025

HiDeoo marked this pull request as draft July 25, 2025 08:16

delucis reviewed Jul 25, 2025

View reviewed changes

docs: add more examples

61bedc2

HiDeoo marked this pull request as ready for review August 19, 2025 14:13

delucis reviewed Aug 19, 2025

View reviewed changes

delucis added the 🌟 minor Change that triggers a minor release label Aug 22, 2025

delucis added this to the v0.36 milestone Aug 22, 2025

HiDeoo added 4 commits August 26, 2025 14:49

refactor: clean up and use variable

b4dbc6d

chore: remove demo content

a6894c1

chore: add changeset

67ddf34

delucis approved these changes Aug 28, 2025

View reviewed changes

delucis added the ✅ approved Pull requests that have been approved and are ready to merge when next cutting a release label Aug 28, 2025

delucis merged commit 2018c31 into withastro:main Sep 19, 2025
23 of 27 checks passed

astrobot-houston mentioned this pull request Sep 19, 2025

[ci] release #3434

Merged

Uh oh!

Fix Astro Island margins in Markdown #3340

Fix Astro Island margins in Markdown #3340

Conversation

HiDeoo commented Jul 25, 2025

Description

Uh oh!

changeset-bot bot commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

astrobot-houston commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

delucis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

delucis commented Jul 25, 2025

Uh oh!

HiDeoo commented Jul 25, 2025

Uh oh!

trueberryless commented Jul 25, 2025

Uh oh!

HiDeoo commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HiDeoo commented Aug 19, 2025

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

HiDeoo commented Aug 20, 2025

Uh oh!

delucis commented Aug 22, 2025

Uh oh!

HiDeoo commented Aug 26, 2025

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

trueberryless commented Aug 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot bot commented Jul 25, 2025 •

edited

Loading

netlify bot commented Jul 25, 2025 •

edited

Loading

astrobot-houston commented Jul 25, 2025 •

edited

Loading

delucis left a comment •

edited

Loading

HiDeoo commented Jul 29, 2025 •

edited

Loading