Icons Changed
Breaking Change in 1.0.0-rc.144
The :[collect:name size/color]: syntax has been deprecated. Please use ::collect:name =size /color:: instead.
The theme plans to support icon libraries such as iconfont, fontawesome, and lucide in future versions. The original syntax was insufficient for these new extensions, making this breaking change necessary.
The old syntax remains supported in recent versions but is no longer recommended and will be removed in the future.
The theme detects if the old syntax is used. If so, it will output warning messages and modification suggestions in the console. Please adjust according to these suggestions.
Overview
The theme supports icons from the following sources in Markdown files:
- iconify - Supported by default
- iconfont - Optional
- fontawesome - Optional
The theme provides Markdown syntax support for icons, offering a simple and flexible way to insert icons in Markdown.
The theme also provides <Icon /> component support. Click to learn more
Syntax
Icon syntax is inline syntax and can be mixed with other Markdown syntax within paragraphs.
Basic Syntax: Use :: to wrap the icon name:
::name::Setting Icon Size and Color: (Note: Spaces are required)
::name =size::
::name /color::
::name =size /color::=size: Set icon size=16: Icon width and height are16px=24x16: Icon width is24px, height is16px=x16: Icon height is16px, width is auto=1.2em: Icon width and height are1.2em=1.2emx1.5em: Icon width is1.2em, height is1.5em
/color: Set icon color, supportshex/rgb/rgba/hsl/hslaand other valid color values/#fff: Icon color is#fff/rgb(255,0,0): Icon color isrgb(255,0,0)
Iconify
iconify provides support for 200K+ open source icons, sufficient for most project needs. The theme uses iconify as the default icon source.
Use the ::collect:name syntax in Markdown to insert icons.
Configuration
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
markdown: {
icon: { provider: 'iconify' } // Supported by default
}
})
})interface IconOptions {
provider: 'iconify'
prefix?: string
}Usage
Search for the desired icon at iconify search and copy the icon name:
Use the
::collect:namesyntax in Markdown to insert the icon::carbon:home::Output:
In Iconify, icons are organized into different collects, each containing several icons. In the ::collect:name syntax, use : to separate collect and name.
If you primarily use icons from a specific collect, you can specify prefix in the configuration to omit the collect prefix in the ::collect:name syntax:
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
markdown: {
icon: {
provider: 'iconify',
prefix: 'carbon', // Use `carbon` icon collection by default
}
}
})
})::home:: <!-- Uses `carbon` icon collection by default, auto-completes to `carbon:home` -->
::solar:user-bold:: <!-- Explicitly use other icon collections -->Output:
Installation
For enterprise internal projects or situations where external network resources cannot be accessed, the theme recommends installing the @iconify/json dependency.
The theme automatically parses icon data from @iconify/json and packages used icons as local resources.
pnpm add @iconify/jsonyarn add @iconify/jsonnpm install @iconify/jsonExamples
Input:
github: ::tdesign:logo-github-filled::
Change color: ::tdesign:logo-github-filled /#f00::
Change size: ::tdesign:logo-github-filled =36px::
Change size and color: ::tdesign:logo-github-filled =36px /#f00::
Colorful icon ::skill-icons:vscode-dark =36px::Output:
github: Change color: Change size: Change size and color:
Colorful icon
Iconfont
iconfont provides massive icon support.
Configuration
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
markdown: {
icon: {
provider: 'iconfont',
assets: 'https://at.alicdn.com/t/c/xxxx.css' // Example URL
}
}
})
})interface IconOptions {
provider: 'iconfont'
/**
* Icon prefix
* @default 'iconfont icon-'
*/
prefix?: string
/**
* iconfont resource URL
*/
assets: string | string[]
}Usage
Go to iconfont Help Center to learn about Creating Projects and Adding Icons
Get the project resource URL from iconfont, copy and paste it into the
assetsconfiguration:
export default defineUserConfig({ theme: plumeTheme({ markdown: { icon: { provider: 'iconfont', assets: 'https://at.alicdn.com/t/c/xxxx.css' // Example URL } } }) })You can also choose to download it locally, store the resources in the
.vuepress/publicdirectory, and then fill in the local file path in theassetsconfiguration.Check the iconfont project configuration to get the
prefixconfiguration:
The
prefixconfiguration consists offont familyandfont classprefix. If the iconfont project uses default settings, thenprefixisiconfont icon-, in which case you can skip this step.export default defineUserConfig({ theme: plumeTheme({ markdown: { icon: { provider: 'iconfont', prefix: 'iconfont icon-', // Default value } } }) })Use the
::name::syntax in Markdown to insert icons:
Fill the
font classfrom the image into the::name::syntax:::hot:: ::hot =24px:: ::hot =24px /#f00::Output:
Fontawesome
Fontawesome provides both free and paid icon support. Paid icons require a subscription.
View Fontawesome official documentation
Configuration
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
markdown: {
icon: {
provider: 'fontawesome',
assets: 'fontawesome' // Preset resource URL, loaded from CDN
}
}
})
})interface IconOptions {
provider: 'fontawesome'
/**
* Icon prefix
* @default 'fas'
*/
prefix?: FontAwesomePrefix
/**
* iconfont resource URL
*/
assets: (FontAwesomeAssetBuiltin | string)[]
}
type FontAwesomeAssetBuiltin = 'fontawesome' | 'fontawesome-with-brands'
type FontAwesomePrefix
= | 'fas' | 's' // fa-solid fa-name
| 'far' | 'r' // fa-regular fa-name
| 'fal' | 'l' // fa-light fa-name
| 'fat' | 't' // fa-thin fa-name
| 'fads' | 'ds' // fa-duotone fa-solid fa-name
| 'fass' | 'ss' // fa-sharp fa-solid fa-name
| 'fasr' | 'sr' // fa-sharp fa-regular fa-name
| 'fasl' | 'sl' // fa-sharp fa-light fa-name
| 'fast' | 'st' // fa-sharp fa-thin fa-name
| 'fasds' | 'sds' // fa-sharp-duotone fa-solid fa-name
| 'fab' | 'b' // fa-brands fa-nameIn Fontawesome, icons are controlled by families + styles. View details
For easier management, you can use the ::prefix:name:: syntax to set families + styles through the prefix. The default prefix is fas, which can be omitted:
::name:: <!-- prefix = fas -->
::fas:name:: <!-- prefix = fas -->
::s:name:: <!-- prefix = fas, s is shorthand for fas -->You can modify the default prefix by configuring markdown.icon.prefix.
Tips
Fontawesome's free icons only support solid, some regular, and brands. For the free version, prefixes only support fas / far / fab and their shorthand prefixes.
Usage
Go to https://fontawesome.com/search?ic=free to search for free icons
Copy the icon name:
Use the
::prefix:name::syntax in Markdown to insert the icon:::circle-user:: <!-- prefix = fas --> ::fas:circle-user:: <!-- prefix = fas --> ::s:circle-user:: <!-- prefix = fas, s is shorthand for fas -->
Examples
::circle-user::
::circle-user =24px::
::circle-user =24px /#f00::Output:
Add more style support for Fontawesome
::circle-user 2xl:: <!-- 2xl is shorthand for fa-2xl, icon size is 2em -->
::circle-user rotate-90:: <!-- icon rotated 90 degrees -->
::circle-user beat:: <!-- icon animation -->
::circle-user border:: <!-- icon border -->
::circle-user 2xl beat:: <!-- mixed styles -->Output:
Additional Notes
When markdown.icon.provider is set to a value other than iconify, iconify remains supported by default, and you can still insert iconify icons in Markdown:
In the ::collect:name:: syntax, add iconify at the beginning:
::iconify carbon:home::Output:
