- parseIconName requires `collection:name`; bare simple-icons names are
qualified by VPSocialLink alone, with a build warning suggesting
qualification when a bare name reaches generation any other way
- collection resolution keeps loadCollectionFromFS (any level of the
project tree) and falls back generically to the @iconify-json/*
packages in vitepress's own dependencies instead of hardcoding
simple-icons; the attribution comment special case is dropped
- fix the mpa/spa parity test on windows (path.basename, not split('/'))
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Icon styles are generated at build time from collections installed locally, and dev mode serves them from the dev server — no icon is ever fetched from an external service. Icons rendered only on the client (e.g. inside `<ClientOnly>`) can't be detected during the build; list them in [`icons.include`](site-config#icons) instead.
Icon styles are generated at build time from collections declared in your project's dependencies, and dev mode serves them from the dev server — no icon is ever fetched from an external service. Bare names are a `socialLinks` convenience and map to simple-icons; everywhere else icons are written as `collection:name`. Icons rendered only on the client (e.g. inside `<ClientOnly>`) can't be detected during the build; list them in [`icons.include`](site-config#icons) instead.
To render one of these icons in your own Markdown or components, use the `VPIcon` component from `vitepress/theme` (`<VPIconicon="lucide:rocket"/>`), or the lower-level `useIcon` composable from `vitepress` when building a custom theme.
To render one of these icons in your own Markdown or components, use the `VPIcon` component from `vitepress/theme` (`<VPIconicon="lucide:rocket"/>`), or the lower-level `useIcon` composable from `vitepress` when building a custom theme — both take fully qualified names.
@ -493,14 +493,14 @@ Only production builds are affected. `vitepress preview` serves a root-absolute
- Type: `{ include?: string[] }`
Options for the generated icon styles. The build collects every iconify icon rendered during SSR ([social links](default-theme-config#sociallinks), the `VPIcon` theme component, or any element registered through the `useIcon` composable) and emits their styles as a hashed `assets/vp-icons.<hash>.css` asset. Names are `name` (resolved in [simple-icons](https://simpleicons.org/)) or `collection:name` for any `@iconify-json/*` collection installed in your project.
Options for the generated icon styles. The build collects every iconify icon rendered during SSR ([social links](default-theme-config#sociallinks), the `VPIcon` theme component, or any element registered through the `useIcon` composable) and emits their styles as a hashed `assets/vp-icons.<hash>.css` asset. Names are fully qualified as `collection:name`, resolved against the `@iconify-json/*` packages declared in your project's dependencies (`socialLinks` is the one place bare names are accepted — they map to [simple-icons](https://simpleicons.org/), which VitePress itself depends on).
Icons rendered only on the client — inside `<ClientOnly>`, or after hydration — are invisible to SSR collection. List them in `include` to force them into the stylesheet:
```ts
export default {
icons: {
include: ['mdi:home', 'discord']
include: ['mdi:home', 'simple-icons:discord']
}
}
```
@ -680,7 +680,7 @@ interface SSGContext {
}
```
Custom themes can add icon names (`name` for simple-icons, or `collection:name`) to `vpIcons` during SSR to have their styles emitted — the `useIcon` composable from `vitepress` does this for you.
Custom themes can add qualified `collection:name` icon names to `vpIcons` during SSR to have their styles emitted — the `useIcon` composable from `vitepress` does this for you.
Divyansh Singh
2 weeks ago