withastro · HiDeoo · Mar 20, 2025 · Mar 21, 2025 · Mar 21, 2025 · Mar 21, 2025
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -70,6 +70,8 @@ export default defineConfig({
 			customCss: ['./src/assets/landing.css'],
 			locales,
 			sidebar: [
+				// TODO(HiDeoo) Remove me
+				{ slug: 'test', badge: { text: 'Remove me', variant: 'danger' } },
 				{
 					label: 'Start Here',
 					translations: {

diff --git a/docs/package.json b/docs/package.json
@@ -18,6 +18,7 @@
   "dependencies": {
     "@astro-community/astro-embed-youtube": "^0.5.6",
     "@astrojs/starlight": "workspace:*",
+    "@iconify-json/mdi": "^1.2.3",
     "@lunariajs/core": "^0.1.1",
     "@types/culori": "^2.1.1",
     "astro": "^5.5.3",

diff --git a/docs/src/components/icons-list.astro b/docs/src/components/icons-list.astro
@@ -1,6 +1,6 @@
 ---
 import { Icon } from '@astrojs/starlight/components';
-import { Icons, type StarlightIcon } from '../../../packages/starlight/components/Icons';
+import { Icons, type StarlightIcon } from '../../../packages/starlight/utils/icons';
 
 interface Props {
 	labels?: {

diff --git a/docs/src/content/docs/components/asides.mdx b/docs/src/content/docs/components/asides.mdx
@@ -132,6 +132,36 @@ A warning aside *with* a custom title.
 
 </Preview>
 
+### Use custom icons
+
+Override the default aside icons by using the [`icon`](#icon) attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
+
+<Preview>
+
+```mdx 'icon="starlight"'
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip" icon="starlight">
+	A warning aside *with* a custom icon.
+</Aside>
+```
+
+<Fragment slot="markdoc">
+
+```markdoc 'icon="starlight"'
+{% aside type="tip" icon="starlight" %}
+A warning aside *with* a custom icon.
+{% /aside %}
+```
+
+</Fragment>
+
+<Aside slot="preview" type="tip" icon="starlight">
+	A warning aside *with* a custom icon.
+</Aside>
+
+</Preview>
+
 ## `<Aside>` Props
 
 **Implementation:** [`Aside.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Aside.astro)
@@ -156,3 +186,9 @@ The type of aside to display:
 
 The title of the aside to display.
 If `title` is not set, the default title for the current aside `type` will be used.
+
+### `icon`
+
+**type:** `string`
+
+An aside can include an `icon` attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
diff --git a/docs/src/content/docs/guides/authoring-content.mdx b/docs/src/content/docs/guides/authoring-content.mdx
@@ -151,6 +151,21 @@ Astro helps you build faster websites with [“Islands Architecture”](https://
 :::
 ```
 
+### Custom aside icons
+
+You can specify a custom icon for the aside in curly braces following the aside type, e.g. `:::tip{icon="starlight"}`, set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons).
+This syntax can be combined with [custom aside titles](#custom-aside-titles), e.g. `:::tip[Did you know?]{icon="starlight"}`.
+
+:::tip{icon="starlight"}
+Starlight supports custom icons for asides.
+:::
+
+```md
+:::tip{icon="starlight"}
+Starlight supports custom icons for asides.
+:::
+```
+
 ### More aside types
 
 Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up.

diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
@@ -645,3 +645,21 @@ starlight({
 	credits: true,
 });
 ```
+
+### `icons`
+
+**type:** `AstroIconOptions`
+
+Starlight uses [Astro Icon](https://www.astroicon.dev/) to render Iconify and local icons.
+See the [“Iconify icons”](/reference/icons/#iconify-icons) and [“Local icons”](/reference/icons/#local-icons) guides to learn how to use custom icons in your project.
+
+You can use any of the standard [Astro Icon configuration options](https://www.astroicon.dev/reference/configuration/) by setting them in Starlight’s `icons` option.
+For example, set Astro Icon’s `iconDir` option to override the default location for local icons:
+
+```js ins={2-4}
+starlight({
+	icons: {
+		iconDir: 'src/logos',
+	},
+});
+```
diff --git a/docs/src/content/docs/reference/icons.mdx b/docs/src/content/docs/reference/icons.mdx
@@ -4,6 +4,7 @@ description: An overview of all the icons available in Starlight.
 ---
 
 Starlight provides a set of built-in icons that you can display in your content using the `<Icon>` component.
+Icon sets from [Iconify](https://iconify.design/) and local icons are also supported and can be used similarly.
 
 ## Use icons
 
@@ -12,7 +13,7 @@ They are also often used in other components, such as [cards](/components/cards/
 
 ## `StarlightIcon` type
 
-Use the `StarlightIcon` TypeScript type to reference the names of [Starlight’s built-in icons](#all-icons).
+Use the `StarlightIcon` TypeScript type to reference the names of [Starlight’s supported icons](#all-icons).
 
 ```ts {2} /icon: (StarlightIcon)/
 // src/icon.ts
@@ -25,8 +26,109 @@ function getIconLabel(icon: StarlightIcon) {
 
 ## All icons
 
-A list of all available icons is shown below with their associated names. Click an icon to copy its name to your clipboard.
+### Built-in icons
+
+A list of all built-in icons is shown below with their associated names. Click an icon to copy its name to your clipboard.
 
 import IconsList from '~/components/icons-list.astro';
 
 <IconsList labels={{ copied: 'Copied!' }} />
+
+### Iconify icons
+
+[Iconify](https://iconify.design/) distributes a wide range of icon sets that can also be used in Starlight just like the built-in icons.
+Starlight uses [Astro Icon](https://www.astroicon.dev/) to support Iconify icons.
+
+To get started, visit the [Iconify icon sets library](https://icon-sets.iconify.design/) or the [Icônes website](https://icones.js.org/) to find the icon set you want to use.
+
+The following example shows how to use the [`music` icon](https://icones.js.org/collection/lucide?s=music&icon=lucide:music) from the [Lucide](https://lucide.dev/) icon set.
+
+import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+
+<Steps>
+
+1.  Install the Iconify Lucide icon set:
+
+    <Tabs syncKey="pkg">
+
+    <TabItem label="npm">
+
+    ```sh
+    npm install @iconify-json/lucide
+    ```
+
+    </TabItem>
+
+    <TabItem label="pnpm">
+
+    ```sh
+    pnpm add @iconify-json/lucide
+    ```
+
+    </TabItem>
+
+    <TabItem label="Yarn">
+
+    ```sh
+    yarn add @iconify-json/lucide
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+2.  Use the icon in any use-case that supports built-in icons by using the Iconify icon identifier.
+
+    For example, to use the Iconify icon with the `<Icon>` component, set the `name` attribute to `lucide:music`.
+
+    ```mdx
+    import { Icon } from '@astrojs/starlight/components';
+
+    <Icon name="lucide:music" />
+    ```
+
+</Steps>
+
+### Local icons
+
+Local icons are SVG files stored in a directory of your choice within your project, optimized using [SVGO](https://svgo.dev/) and usable just like any other icon.
+Starlight uses [Astro Icon](https://www.astroicon.dev/) to support local icons.
+
+By default, local icons are expected to be in the `src/icons/` directory of your project.
+SVGO options and the icon directory can be configured using the [`starlight.icons`](/reference/configuration/#icons) property in `astro.config.mjs`.
+
+The following example shows how to use a `logo.svg` SVG file as an icon.
+
+import { FileTree } from '@astrojs/starlight/components';
+
+<Steps>
+
+1.  Copy the `logo.svg` SVG file to the `src/icons/` directory of your project.
+
+    <FileTree>
+
+    - src/
+      - content/
+        - docs/
+          - guides/
+            - guide.md
+            - index.md
+        - icons/
+          - **logo.svg**
+    - astro.config.mjs
+
+    </FileTree>
+
+2.  Use the icon in any use-case that supports built-in icons by using the slug of the icon file.
+
+    For example, to use the `logo.svg` SVG file with the `<Icon>` component, set the `name` attribute to `logo`.
+
+    ```mdx
+    import { Icon } from '@astrojs/starlight/components';
+
+    <Icon name="logo" />
+    ```
+
+</Steps>
+
+To learn more about how to use local icons, check out the [“Local icons”](https://www.astroicon.dev/guides/customization/#local-icons) guide in the Astro Icon docs.