Add support for custom icons

[HiDeoo]

Description

• Closes Support external icons since built-in icons are too limited #967
• Closes Adding custom icons to cards #2807

This PR is a very early draft adding support for Iconify and local icons in Starlight.

The early draft PR is opened to provide some material for discussions and also evaluate potential changes in involved libraries. A lot of work, including more robust implementations for some parts, more tests, and documentation, is still needed.

Preview test page: https://deploy-preview-3024--astro-starlight.netlify.app/test/

Implementation

Most of the implementation relies on the Astro Icon library, altho Starlight does not only uses icons through components but also in different contexts, e.g. remark plugins.

A few high-level details about the implementation:

• No breaking changes are introduced for existing icons. Starlight's built-in icons are still available and can be used as before.
• Starlight does not ship with any Iconify icon set (built-in icons are still part of Starlight and not transformed in an Iconify icon set).
• Users can choose to install any Iconify icon set they want to use.
• Everywhere a built-in icon can be used, an Iconify or local icon can be used as well.
• Custom aside icons is built upon Aside: Support custom icons #2261 (which should be merged first for credits), refactored to also support Iconify icons.

Astro Icon configuration

Astro Icon is an integration that supports various configuration options.

Just like expressiveCode, Astro Icon options are currently exposed using an icons (placeholder name) property in the Starlight configuration.

Astro Icon notes

Here are a few notes about Astro Icon that I gathered so far that I would like to discuss with the maintainers of the project (still need to put them in a more friendly format):

• The issue regarding icon sets not being found when icon sets are part of a library:
  • This issue seems to be related to how installed icon sets are determined which was changed in this PR to fix other issues, e.g. different results with different package managers or when NODE_ENV is set to production.
  • This issue does not affect the current implementation as Starlight does not ship with any Iconify icon set and users have to install them themselves in their projects.
  • This could be an issue if a Starlight plugin decides to ship with an Iconify icon set and use it in its components.
  • I didn't spend enough time yet on the issue, but it seems like the previous approach may work by appending --prod=false to the list command from my initial and quick tests. Will need to investigate more.
• When using the @iconify/utils helper loadCollectionFromFS() to load collections, by default this helper uses process.cwd() to load collections. Same goes for the importDirectory() helper in @iconify/tools used to load local icons.
  • This can be an issue in some cases, e.g. in Starlight E2E tests where the current working directory is not the project root.
  • This PR includes a patch to Astro Icon using an absolute path.
• As Starlight uses icons in contexts where Astro Icon cannot be used, e.g. remark plugins, we also need to load local and Iconify icons in such contexts:
  • This PR ships (very) similar implementations to Astro Icon's Iconify and local icons loaders.

Remaining tasks

• Address all remaining // TODO(HiDeoo) comments
• Changesets covering all changes across all changed packages
  • @astrojs/starlight
  • @astrojs/starlight-markdoc
• Remove some test files
  • docs/src/icons/test.svg
  • docs/src/content/docs/test.mdx
  • examples/markdoc/src/content/docs/test.mdoc
• Uninstall @iconify-json/mdi from starlight-docs and @example/starlight-markdoc
• Documentation
  • Very early draft documentation just to expose what changed and should definitely be improved
  • In a lot of places, we mention "one of Starlight’s built-in icons" with a link. The sentence should be updated (maybe "supported icons"?) and the link should be updated too if needed.
• Merge Aside: Support custom icons #2261 before this PR

[changeset-bot]

⚠️ No Changeset found

Latest commit: 15abae3

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

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	15abae3
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67f01239effe6f00086afbd3
😎 Deploy Preview	https://deploy-preview-3024--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 site configuration.

[astrobot-houston]

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	components/asides.mdx	Source changed, localizations will be marked as outdated.
en	guides/authoring-content.mdx	Source changed, localizations will be marked as outdated.
en	reference/configuration.mdx	Source changed, localizations will be marked as outdated.
en	reference/icons.mdx	Source changed, localizations will be marked as outdated.
en	test.mdx	Source added, will be tracked.

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.