vuepress-theme-plume/docs/en/guide/markdown/icons.md

title, createTime, icon, permalink, badge

title	createTime	icon	permalink	badge
Icons	2025/10/08 14:49:39	grommet-icons:emoji	/en/guide/markdown/icon/	text type Changed warning

::: warning 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{.read-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 are 16px
  • =24x16: Icon width is 24px, height is 16px
  • =x16: Icon height is 16px, width is auto
  • =1.2em: Icon width and height are 1.2em
  • =1.2emx1.5em: Icon width is 1.2em, height is 1.5em

• /color: Set icon color, supports hex/rgb/rgba/hsl/hsla and other valid color values

  • /#fff: Icon color is #fff
  • /rgb(255,0,0): Icon color is rgb(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: { // [!code ++:3]
      icon: { provider: 'iconify' } // Supported by default
    }
  })
})

interface IconOptions {
  provider: 'iconify'
  prefix?: string
}

Usage

::: steps

• Search for the desired icon at iconify search and copy the icon name:

  

• Use the ::collect:name syntax in Markdown to insert the icon

  ::carbon:home::
  

  Output: ::carbon:home::

:::

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 // [!code ++]
      }
    }
  })
})

::home::    <!-- Uses `carbon` icon collection by default, auto-completes to `carbon:home` -->
::solar:user-bold::  <!-- Explicitly use other icon collections -->

Output: ::carbon:home:: ::solar:user-bold::

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.

::: npm-to

npm install @iconify/json

:::

Examples

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: ::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::

Iconfont

iconfont provides massive icon support.

Configuration

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    markdown: { // [!code ++:3]
      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{.read-more}

:::steps

• Get the project resource URL from iconfont, copy and paste it into the assets configuration:

  

  export default defineUserConfig({
    theme: plumeTheme({
      markdown: {
        icon: {
          provider: 'iconfont',
          assets: 'https://at.alicdn.com/t/c/xxxx.css' // Example URL // [!code ++]
        }
      }
    })
  })
  

  You can also choose to download it locally, store the resources in the .vuepress/public directory, and then fill in the local file path in the assets configuration.

• Check the iconfont project configuration to get the prefix configuration:

  

  The prefix configuration consists of font family and font class prefix. If the iconfont project uses default settings, then prefix is iconfont icon-, in which case you can skip this step.

  export default defineUserConfig({
    theme: plumeTheme({
      markdown: {
        icon: {
          provider: 'iconfont',
          prefix: 'iconfont icon-', // Default value  // [!code ++]
        }
      }
    })
  })
  

• Use the ::name:: syntax in Markdown to insert icons:

  

  Fill the font class from 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{.read-more}

Configuration

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    markdown: { // [!code ++:3]
      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-name

In Fontawesome, icons are controlled by families + styles. View details{.read-more}

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.

::: tip 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{.read-more}

:::steps

• 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{.read-more}

::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:

::iconify carbon:home::