fix: prevent list items from overflowing Markdown content

[julien-deramond]

---

⚠️ If this is not going to right direction, feel free to close the PR directly. If this is the right solution, please don't forget to remove:

• the reddish background
• the additional fake content

---

Description

Context

This PR is an attempt to fix an issue reported in this Discord > starlight > Text overflow issue thread.

On iPhone XR, OP could see on a 414px width screen the following (at https://0d6fe6ee.chart-docs.pages.dev/charts/dependency/kube-state-metrics/) which results in a horizontal scrollbar:

It can also be observed, at least on macOS with Safari and Chrome.

Changes

As you can see in the deployed documentation, I've tested some long links in the regular content, but also in ordered and unordered lists. Regular content is fine, while the long links in the lists are overflowing.

The idea here is to rely on the same fixes that happened in #756 and #814 based on the use of overflow-wrap: anywhere.

Not knowing in detail the codebase of Starlight, I suppose that reducing the scope to .sl-markdown-content li is acceptable (I've added a reddish background for visual manual regression testing). Indeed, adding this rule directly in the reset.css might have some unexpected repercussions.

Here's the rendering before the fix.

Here's the rendering after the fix (directly accessible at https://starlight-git-fork-julien-deramond-main-jd-bab67d-astrodotbuild.vercel.app/guides/authoring-content/):

Non-regression testing

I'm sorry but I haven't tested yet some impacts that would maybe need a stricter CSS rule, and I'll be off for 1 week tomorrow.

Some use cases that could be impacted:

• https://starlight-git-fork-julien-deramond-main-jd-bab67d-astrodotbuild.vercel.app/getting-started/: tabs if there are too much of them
• https://starlight-git-fork-julien-deramond-main-jd-bab67d-astrodotbuild.vercel.app/guides/project-structure/#example-project-contents: directories list with some long names or too many sub-directories
• https://starlight-git-fork-julien-deramond-main-jd-bab67d-astrodotbuild.vercel.app/guides/css-and-tailwind/#custom-css-styles: complex lists with graphical elements in them
• https://starlight-git-fork-julien-deramond-main-jd-bab67d-astrodotbuild.vercel.app/guides/customization/#add-your-logo: combo of previous mentioned use cases
• https://starlight-git-fork-julien-deramond-main-jd-bab67d-astrodotbuild.vercel.app/resources/community-content/#astro-videos: list of cards

[changeset-bot]

⚠️ No Changeset found

Latest commit: e620ec7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	Apr 10, 2024 5:28pm

[delucis]

Thank you for jumping into this so quickly @julien-deramond!

I did some quick testing across the Starlight docs to investigate the potential for regressions (hard to be sure for all user content, so I’m hoping our range of content is a good enough test case).

I did find one specifically in our <Tabs> component that should never wrap and instead scroll horizontally when they overflow:

I guess we’ll need to override the overflow-wrap: anywhere for that component. It also gives a small indication that this could have an impact on user components in theory.

It makes me wonder if our global rule setting this should be scoped to the Markdown content and use :not(:where(.not-content *)) like the other rules to make it easier for users to escape that styling if needed. This rule here:

https://github.com/withastro/starlight/blob/main/packages/starlight/style/reset.css#L35-L44

[julien-deramond]

I guess we’ll need to override the overflow-wrap: anywhere for that component. It also gives a small indication that this could have an impact on user components in theory.

Yes, if it is difficult to measure the impact on Starlight side, we can be sure that it will have an impact on users' components.

It makes me wonder if our global rule setting this should be scoped to the Markdown content and use :not(:where(.not-content *)) like the other rules to make it easier for users to escape that styling if needed. This rule here:

https://github.com/withastro/starlight/blob/main/packages/starlight/style/reset.css#L35-L44

My first version was adding li to this rule, but it was a little bit "scary" not to be able to measure the impact and the potential regressions for the users, not knowing all the details of the codebase.

I'd be in favor to scope it to the Markdown content. It would seem to be the most maintainable approach for the Starlight core team, and maybe also less opinionated and/or impactful for the users and their components, yeah.

[HiDeoo]

Thanks for the great contribution. We reviewed this PR with a lot of eyes/devices/browsers today in Astro Talking & Doc'ing session.

To do so, we had everyone browse random pages on various Starlight websites (Starlight Docs, Astro Docs, SST Ion docs and Knip Docs) where I implemented ahead of time the suggested fix from this PR.

With exactly the suggested changes from this PR, no extra issue except the one spotted by Chris regarding the <Tabs> component was found.

We tried a slight variation of the selector (.sl-markdown-content li:not(:where(.not-content *))) which prevents this issue as the tabs list wrapper uses the not-content class. Altho, as spotted during the session, this would not work in the case of the <Tabs> component nested in the <Steps> component for example.

Did not play more than that yet with the selector, but I guess it will need a bit more tweaking to handle those cases.