Icon support
The entire theme adds FontClass and Image format icon support in multiple places.
You can use iconfont, iconify and fontawesome to add icons to your project, and you can also use your own icon assets. Also, png/svg format icon is supported. You can use full links or pathname to add icons.
We recommend you to use iconify or fontawesome.
Browsing Icon List
- Iconify: https://icon-sets.iconify.design/
- Iconfont: https://www.iconfont.cn/?lang=en-us
- Fontawesome: https://fontawesome.com/search?o=r&m=free
Setting Icons
You can use icon in multiple places.
Page: set
icon
in frontmatterThis icon will be used in breadcrumb, page title, navbar generated item, sidebar generated item, page nav, etc.
Navbar: set
icon
option in NavbarItemConfigSidebar: set
icon
option in SidebarItemConfigHomePage: set
icon
option in feature item
Adding Icons in Markdown
You can use <HopeIcon />
component to add icon in markdown.
icon
prop accepts the same content as othericon
options, i.e.: font class and image urlcolor
prop accepts a css color value, which will be used as the icon color (optional)size
prop accepts a css size value, which will be used as the icon size (optional)
Demo
- <HopeIcon icon="home" color="red" />
- <HopeIcon icon="//theme-hope-assets.vuejs.press/logo.svg" size="4rem" verticalAlign="middle" />
Global Settings
You can set icon assets url and icon prefix globally via iconAssets
and iconPrefix
.
Setting Icon Assets
You should set icon related assets to iconAssets
, where you can set:
- icon assets keywords
- icon resource in format of css and js
- array of above
import { hopeTheme } from "vuepress-theme-hope";
export default {
theme: hopeTheme({
// keywords: "iconify", "fontawesome", "fontawesome-with-brands"
iconAssets: "fontawesome",
// an url you like
iconAssets: "/base/my/font-icon/resource.js",
// an array of above
iconAssets: [
"/base/my/font-icon/resource.js",
"https://example/my/fonr-icon/resouce.css",
"fontawesome",
],
}),
};
For example, you may use iconfont.cn and fontawesome to generate your own assets.
To keep it simple, we add built-in keywords "iconify"
, "fontawesome"
and "fontawesome-with-brand
support for you to get started easily.
Caution
If you use this plugin for commercial project documentation, iconfont
is not recommended as iconfont itself is a study/share platform for designers and developers.
Every icon is uploaded by users, and you must get authorized from the author for commercial usage. Also, there could be chance where the uploader obeys usage term. And upload icons where its copyright is at 3rd party.
Setting Icon Prefix
iconPrefix
is the icon prefix where you want to set,
Normally, there should be a common prefix for your icon class, for iconfont
icon classes are iconfont icon-<ICON-NAME>
and for fontawesome free icon classes are fas fa-<icon-name>
. So when you are setting the above assets
option with keywords or a single link generated from iconfont website, fontawesome kit or fontawesome CDN, the plugin recognize those and set prefix as "iconfont icon-"
and "fas fa-"
automatically for you.
In other cases where you use iconify or your own url, you can manually set this options yourself. After all writing icon: apple
is always better than something like icon: iconfont icon-apple
, icon: mdi:icon-apple
or icon: fa-solid fa-apple
.
Advanced
Using Fontawesome Kits
You can purchase at fontawesome.com to use kits or import brand icons.
Fontawesome kits with pro features support pro icons, more icon styles and uploading your own icons.
Generate your own iconfont assets
Iconfont
Iconfont is a vector icon management and communication platform created by Alimama MUX.
The designer uploads the icon to the Iconfont platform, and the user can customize the download of icons in a variety of formats. Users can also convert the icon into a font.
How to use
First, you need to create a new project to set and manage your website's icons:
- Log in to Iconfont using GitHub or Weibo.
- Find "Resources → My Projects" at the top of the website, and click the "New Project" icon in the upper right corner.
- Set a recognizable project name
- Fill in
FontClass/Symbol prefix
withicon-
(you can also fill in according to your preference, but you need to set this value toiconPrefix
in theme options with an extraiconfont
prefix) - Font Family please keep
iconfont
Import Icon
Search freely through iconfont to find the icon you want to use, and click the "Add to Library" button on the icon
After searching for all the icons, click the "Add to Library" icon in the upper right corner, click "Add to Project" below and select the project you created then confirm.
Edit Icon
On the project page, you can edit the icons in the project, including adjustments with position, size, rotate, color, Unicode number and Font Class / Symbol.
Generate Icon Files
Please click the "Font Class" button above the project and click Generate.
Set the css link to
iconAssets
in theme options.
Tips
Tips
If you add a new icon in the future, please regenerate the new CSS address and set it to iconAssets
in theme options.
Conflicts with private character
Font Icon associate each icon with a character in unicode private character scope, the character used by iconfont is randomly.
Iconfont will try to solve conflicts by assigning a new character if a new icon's default character is already used in current project, however different projects may have conflicts.
So we do not recommend you to use multiple iconfont links as assets, if you ready want to do so, check the icons to ensure every former project icon is not covered by those in latter ones.