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