Add link icons and dedupe Markdown/component icons by HiDeoo · Pull Request #3967 · withastro/starlight

HiDeoo · 2026-06-18T16:20:08Z

Follow-up to #3923, this PR cleans up various parts regarding aside and heading link icons:

The Unified/Sätteri aside plugins now uses the same Starlight icons as the existing ones already rendered by the <Aside> component
The Unified/Sätteri heading link plugins and <AnchorHeading> component now uses a new common Starlight icon (link-alt to match the Unicons naming)
As it felt weird to only add new link-alt icon, I also added the matching link icon

The diff also shows how much more minified the aside component icons are compared to our previous Markdown plugin ones. I wonder if we forgot to minify them or just used a different preset 🤷

Not quite sure if a changeset for the deduping part of the PR should be added. Visually, nothing changed, and it's mostly SVG path changes. And if yes, not quite sure how to phrase it as my attempts so far kinda hinted wrong icons were rendered which is not the case 😅 Finally managed to write something I'm happy with.

changeset-bot · 2026-06-18T16:20:14Z

🦋 Changeset detected

Latest commit: efa0502

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	Patch

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 · 2026-06-18T16:20:15Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`efa0502`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/6a3c155a01b1500008a78855
😎 Deploy Preview	https://deploy-preview-3967--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
🤖 Make changes	Run an agent on this branch

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

* main: [ci] release (withastro#3956) Astro 7 support (withastro#3951)

HiDeoo · 2026-06-24T09:09:04Z

The diff here is mostly from using SVGOMG with the Unicons link-alt icon which produces a slightly different result compared to the one we had previously.

One thing to note is that fill="currentColor" is now applied to the SVG rather the <path> as we are re-using the path from a Starlight icon now and we re-use the same approach used for all Starlight icons.

HiDeoo · 2026-06-24T09:10:46Z

For this diff and the following ones, the changes are mostly us now re-using the <Aside> component icons for the Markdown asides, and it looks like our Markdown aside icons never got optimized by SVGOMG.

HiDeoo · 2026-06-24T09:12:10Z

We are now using the new and shared link-alt Starlight icon for this component.

HiDeoo · 2026-06-24T09:12:30Z

Removed in favor of a shared link-alt Starlight icon.

HiDeoo · 2026-06-24T09:13:13Z

Icon paths removed in favor of using the same Starlight icons used by the <Aside> component we already had.

HiDeoo · 2026-06-24T09:15:09Z

A set of utility functions for asides now regrouped in this single file, that are used either by the Markdown pipeline (both Unified and Sätteri) and also the <Aside> component.

HiDeoo · 2026-06-24T09:15:34Z

Moved and internalized in packages/starlight/integrations/aside-utils.ts.

HiDeoo · 2026-06-24T09:16:22Z

Mardown pipeline (Unified and Sätteri) specific icons and helpers to consume Starlight icons (extracted from packages/starlight/integrations/remark-asides.ts).

HiDeoo · 2026-06-24T09:20:42Z

Starting from this file, we are now mostly re-using the new (Unified and Sätteri) helpers we have, and removing dead-code.

HiDeoo · 2026-06-24T09:25:29Z

Updated the PR and added some comments to hopefully make the review easier to follow 🤞

delucis

Looks great — thank you for following up on this idea!

I left a few small queries/nits, but nothing major.

Co-authored-by: delucis <357379+delucis@users.noreply.github.com>

delucis

Perfect — thanks @HiDeoo 🙌

delucis · 2026-06-25T12:25:09Z

Going to merge this to get it out in the same patch with #3988, hope that’s ok!

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.41.0` → `0.41.1`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.41.0/0.41.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.41.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.41.0/0.41.1?slim=true) | --- ### Release Notes <details> <summary>withastro/starlight (@astrojs/starlight)</summary> ### [`v0.41.1`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0411) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.41.0...@astrojs/starlight@0.41.1) ##### Patch Changes - [#3967](withastro/starlight#3967) [`72e63dc`](withastro/starlight@72e63dc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds 2 new icons: `link` and `link-alt`. - [#3988](withastro/starlight#3988) [`ac55cfa`](withastro/starlight@ac55cfa) Thanks [@delucis](https://github.com/delucis)! - Fixes a dependency resolution issue introduced in Starlight v0.41 - [#3967](withastro/starlight#3967) [`72e63dc`](withastro/starlight@72e63dc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Optimizes the icons of Markdown asides. </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate).

moeriki · 2026-06-29T13:55:41Z

Hi! Since the last update (0.41.1) I've got Starlight rendering raw SVGs for aside icons.

This happens only in MDX files, not MDs.

Currently I have this patch working for me.

diff --git a/integrations/satteri.ts b/integrations/satteri.ts
index 32a0907d8928a678a02187019509fd34277aeb41..9bd133278877c7488530e021070f9ad734935628 100644
--- a/integrations/satteri.ts
+++ b/integrations/satteri.ts
@@ -112,7 +112,18 @@ function satteriAsidesPlugin(
 				},
 				[
 					paragraphElement('p', { class: 'starlight-aside__title', 'aria-hidden': 'true' }, [
-						{ type: 'html', value: iconSvg },
+						// PATCH: a bare `{ type: 'html' }` node renders in `.md` but is
+						// escaped to literal source in `.mdx` (where raw HTML must be a
+						// `set:html` Fragment). Emit Sätteri's MDX-safe Fragment form so
+						// the icon renders in MDX. See upstream withastro/starlight #3967.
+						{
+							type: 'mdxJsxTextElement',
+							name: 'Fragment',
+							attributes: [
+								{ type: 'mdxJsxAttribute', name: 'set:html', value: iconSvg },
+							],
+							children: [],
+						},
 						...titleNode,
 					]),
 					paragraphElement('div', { class: 'starlight-aside__content' }, children),

It looks like it might be related to this change.

HiDeoo · 2026-06-29T14:04:52Z

👋 @moeriki

Would you be able to share a minimal reproduction of the issue, e.g. on StackBlitz? So far, I'm not able to reproduce such behavior, for example here is StackBlitz with many asides in MDX: https://stackblitz.com/edit/github-egjmzxro?file=src%2Fcontent%2Fdocs%2Findex.mdx

moeriki · 2026-06-29T14:50:11Z

https://stackblitz.com/edit/github-egjmzxro-hf1kf6yk?file=package.json,astro.config.mjs

I found the issue lies in the fact we integrate our own @astrojs/mdx.

{
  integrations: [
    starlight({ /* … */ }),
    mdx({
      optimize: true,
    }),
  ],
}

Setting optimize: true now also fixed the issue (without the patch).

delucis · 2026-06-29T15:14:10Z

Thanks @moeriki! Looks like the type: "html" approach was working under the assumption of optimize: true (which Starlight sets for users by default in its own copy of the MDX integration if users themselves don’t provide one).

But we should make it work in your scenario too.

delucis · 2026-06-30T18:01:32Z

Opened a PR to fix this: #4015

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`^0.40.0` → `^0.41.0`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.40.0/0.41.3) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.41.3?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.40.0/0.41.3?slim=true) | | [sharp](https://sharp.pixelplumbing.com) ([source](https://github.com/lovell/sharp), [changelog](https://github.com/lovell/sharp/blob/main/docs/src/content/docs/changelog.md)) | [`0.35.2` → `0.35.3`](https://renovatebot.com/diffs/npm/sharp/0.35.2/0.35.3) | ![age](https://developer.mend.io/api/mc/badges/age/npm/sharp/0.35.3?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/sharp/0.35.2/0.35.3?slim=true) | --- ### Release Notes <details> <summary>withastro/starlight (@astrojs/starlight)</summary> ### [`v0.41.3`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0413) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.41.2...@astrojs/starlight@0.41.3) ##### Patch Changes - [#3911](withastro/starlight#3911) [`1686ecc`](withastro/starlight@1686ecc) Thanks [@timothyjordan](https://github.com/timothyjordan)! - Keeps keyboard focus inside the mobile menu while it is open, preventing focus moving to hidden interactive elements in page content. ### [`v0.41.2`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0412) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.41.1...@astrojs/starlight@0.41.2) ##### Patch Changes - [#4008](withastro/starlight#4008) [`58a3520`](withastro/starlight@58a3520) Thanks [@FrancoKaddour](https://github.com/FrancoKaddour)! - Fixes the table of contents overflowing the right edge of the viewport when a custom `--sl-content-width` value exceeds available space - [#4015](withastro/starlight#4015) [`bdbfffc`](withastro/starlight@bdbfffc) Thanks [@delucis](https://github.com/delucis)! - Fixes an issue where aside icons were rendered incorrectly in projects where Astro’s MDX integration had optimization disabled ### [`v0.41.1`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0411) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.41.0...@astrojs/starlight@0.41.1) ##### Patch Changes - [#3967](withastro/starlight#3967) [`72e63dc`](withastro/starlight@72e63dc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds 2 new icons: `link` and `link-alt`. - [#3988](withastro/starlight#3988) [`ac55cfa`](withastro/starlight@ac55cfa) Thanks [@delucis](https://github.com/delucis)! - Fixes a dependency resolution issue introduced in Starlight v0.41 - [#3967](withastro/starlight#3967) [`72e63dc`](withastro/starlight@72e63dc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Optimizes the icons of Markdown asides. ### [`v0.41.0`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0410) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.40.0...@astrojs/starlight@0.41.0) ##### Minor Changes - [#3951](withastro/starlight#3951) [`1202dd4`](withastro/starlight@1202dd4) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Astro v7, drops support for Astro v6. ##### Upgrade Astro and dependencies ⚠️ **BREAKING CHANGE:** Astro v6 is no longer supported. Make sure you [update Astro](https://docs.astro.build/en/guides/upgrade-to/v7/) and any other official integrations at the same time as updating Starlight: ```sh npx @astrojs/upgrade ``` *Community Starlight plugins and Astro integrations may also need to be manually updated to work with Astro v7. If you encounter any issues, please reach out to the plugin or integration author to see if it is a known issue or if an updated version is being worked on.* ⚠️ **BREAKING CHANGE:** This release drops official support for Chromium-based browsers prior to version 111 (released 07 March 2023) and Safari-based browsers prior to version 16.4 (released 27 March 2023). You can find a list of currently supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+111%2C+Edge+%3E%3D+111%2C+Firefox+%3E%3D+121%2C+Safari+%3E%3D+16.4%2C+iOS+%3E%3D+16.4%2C+not+op_mini+all). ##### Patch Changes - [#3953](withastro/starlight#3953) [`a935d33`](withastro/starlight@a935d33) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes Starlight Markdown processing being potentially applied to files that should not be processed. </details> <details> <summary>lovell/sharp (sharp)</summary> ### [`v0.35.3`](https://github.com/lovell/sharp/releases/tag/v0.35.3) [Compare Source](lovell/sharp@v0.35.2...v0.35.3) - Tighten verification of `text` dimensions, TIFF tile dimensions and `extend` values. - Improve code bundler support by resolving path to libvips binary. - Increase default concurrency when use of `MALLOC_ARENA_MAX` is detected. - Emit warning about binaries provided by Electron for use on Linux. - Add `hasAlpha` property to output `info`. [#4500](lovell/sharp#4500) - TypeScript: Return more precise `Buffer<ArrayBuffer>` from `toBuffer`. [#4520](lovell/sharp#4520) [@Andarist](https://github.com/Andarist) - Bound `clahe` width and height to avoid signed overflow. [#4551](lovell/sharp#4551) [@metsw24-max](https://github.com/metsw24-max) - Bound `trim` margin to avoid signed overflow. [#4552](lovell/sharp#4552) [@metsw24-max](https://github.com/metsw24-max) - Reject infinite values when validating numbers. [#4553](lovell/sharp#4553) [@metsw24-max](https://github.com/metsw24-max) - Bound extract region to libvips coordinate limit. [#4555](lovell/sharp#4555) [@metsw24-max](https://github.com/metsw24-max) - Verify background colour values are numbers. [#4556](lovell/sharp#4556) [@metsw24-max](https://github.com/metsw24-max) - Bound create and raw input dimensions to coordinate limit. [#4558](lovell/sharp#4558) [@metsw24-max](https://github.com/metsw24-max) - Tighten recomb and affine matrix verification. [#4560](lovell/sharp#4560) [@chatman-media](https://github.com/chatman-media) - Verify cache memory limit to avoid overflow. [#4561](lovell/sharp#4561) [@metsw24-max](https://github.com/metsw24-max) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that's undesired. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  --------- Co-authored-by: Paul Tibbetts <code@paultibbetts.uk> Reviewed-on: https://gitea.cloud.paultibbetts.uk/paul/dev/pulls/139 Co-authored-by: Renovate Bot <bot@renovateapp.com> Co-committed-by: Renovate Bot <bot@renovateapp.com>

HiDeoo added 5 commits June 18, 2026 15:41

refactor: aside icons and utils

e5923c3

refactor: aside-icons → aside-utils

9dd4be1

refactor: heading link icon

3e60986

feat: add link icon

6d41b82

chore: add changeset

e39e704

github-actions Bot added the 🌟 core Changes to Starlight’s main package label Jun 18, 2026

Merge branch 'main' into hd/anchor-aside-icons

fc73de3

HiDeoo marked this pull request as draft June 23, 2026 19:32

HiDeoo added 2 commits June 24, 2026 10:21

Merge branch 'main' into hd/anchor-aside-icons

e0fba29

* main: [ci] release (withastro#3956) Astro 7 support (withastro#3951)

chore: add changeset

214c632

HiDeoo commented Jun 24, 2026

View reviewed changes

HiDeoo marked this pull request as ready for review June 24, 2026 09:25

delucis reviewed Jun 24, 2026

View reviewed changes

Comment thread packages/starlight/integrations/remark-asides.ts

Comment thread packages/starlight/style/anchor-links.css Outdated

Comment thread .changeset/deep-plants-teach.md Outdated

Comment thread .changeset/wicked-spoons-own.md Outdated

HiDeoo and others added 4 commits June 24, 2026 19:27

feat: add back iconPaths cached remark aside icon paths

5ce68d9

Co-authored-by: delucis <357379+delucis@users.noreply.github.com>

fix: remove outdated margin-top

b33473c

Co-authored-by: delucis <357379+delucis@users.noreply.github.com>

fix: changeset typo

38eaf3d

Co-authored-by: delucis <357379+delucis@users.noreply.github.com>

chore: better changeset

efa0502

Co-authored-by: delucis <357379+delucis@users.noreply.github.com>

delucis approved these changes Jun 25, 2026

View reviewed changes

delucis merged commit 72e63dc into withastro:main Jun 25, 2026
16 checks passed

astrobot-houston mentioned this pull request Jun 25, 2026

[ci] release #3989

Merged

delucis mentioned this pull request Jun 30, 2026

Fix aside icons when MDX optimization is disabled #4015

Merged

Conversation

HiDeoo commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HiDeoo commented Jun 24, 2026

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

delucis commented Jun 25, 2026

Uh oh!

Uh oh!

moeriki commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HiDeoo commented Jun 29, 2026

Uh oh!

moeriki commented Jun 29, 2026

Uh oh!

delucis commented Jun 29, 2026

Uh oh!

delucis commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HiDeoo commented Jun 18, 2026 •

edited

Loading

changeset-bot Bot commented Jun 18, 2026 •

edited

Loading

netlify Bot commented Jun 18, 2026 •

edited

Loading

moeriki commented Jun 29, 2026 •

edited

Loading