feat(plugin-icon): support markdown syntax (#338)

Author: Mister-Hope

docs/plugins/features/icon.md

@@ -26,16 +26,43 @@ export default {
 }
 ```
 
-We support multiple types of icons as well:
+We support multiple types of icons:
 
 - `iconify` (default)
 - `fontawesome`
 - `iconfont`
 
-Also, images links are supported with any icon types (relative links are NOT supported).
+Also, you can use images links with any icon types (relative links are NOT supported).
 
 If you want a new type of icon, please open an issue or submit a PR.
 
+In markdown, you can use `::icon decorators... =size /color key=value complex-key="complex value"...::` to insert custom icons.
+
+- A string starting with `=` will be treated as a size definition.
+- A string starting with `/` will be treated as a color definition.
+- Any string which itself is a valid html attribute will parsed, standardized and added to the icon element.
+- The rest part will be treated as the icon name.
+
+```md
+::icon =16 /red:: <!-- <VPIcon class="icon" color="red" size="16px" -->
+
+::icon rotate vertical-align=middle:: <!-- <VPIcon icon="icon rotate" vertical-align="middle" -->
+```
+
+::: info Demo
+
+::mdi:home /blue::
+::mdi:apple =2rem vertical-align=text-bottom::
+
+```md
+::mdi:home /blue::
+::mdi:apple =2rem vertical-align=text-bottom::
+```
+
+:::
+
+## Icon Types
+
 ### Iconify
 
 For full icon list, see <https://icon-sets.iconify.design/>. To use a icon, copy it's icon name of `iconify-icon` in the selector.
@@ -50,8 +77,8 @@ Additionally, iconify support the following props:
 If you use 1 icon set mostly, you can set the prefix to the icon set name (E.g.: `mdi:`), Then you can use the icon name without the prefix. Manually declaring a full icon name will override the prefix:
 
 ```md
-<VPIcon icon="home" /> <!-- mdi:home -->
-<VPIcon icon="svg-spinners:180-ring" /> <!-- svg-spinners:180-ring -->
+::home:: <!-- mdi:home -->
+::svg-spinners:180-ring:: <!-- svg-spinners:180-ring -->
 ```
 
 ### Font Awesome
@@ -63,38 +90,38 @@ The `fontawesome` keyword only includes the free solid and regular icons. If you
 Solid icons can be used directly. if you want to use regular or brand icons, you need to add the `regular:` or `brands:` prefix to the icon name:
 
 ```md
-<VPIcon icon="home" /> <!-- fas fa-home (solid is default) -->
-<VPIcon icon="solid:home" /> <!-- fas fa-home -->
-<VPIcon icon="regular:heart" /> <!-- far fa-heart -->
-<VPIcon icon="brands:apple" /> <!-- fab fa-apple -->
+::home:: <!-- fas fa-home (solid is default) -->
+::solid:home:: <!-- fas fa-home -->
+::regular:heart:: <!-- far fa-heart -->
+::brands:apple:: <!-- fab fa-apple -->
 ```
 
 Besides, a three letter prefix, first letter or full class name are also supported:
 
 ```md
-<VPIcon icon="s:home" /> <!-- fas fa-home -->
-<VPIcon icon="fas:home" /> <!-- fas fa-home -->
-<VPIcon icon="fa-solid:home" /> <!-- fa-solid fa-home -->
+::s:home:: <!-- fas fa-home -->
+::fas:home:: <!-- fas fa-home -->
+::fa-solid:home:: <!-- fa-solid fa-home -->
 
-<VPIcon icon="b:apple" /> <!-- fab fa-apple -->
-<VPIcon icon="fab:apple" /> <!-- fab fa-apple -->
-<VPIcon icon="fa-brands:apple" /> <!-- fa-brands fa-apple -->
+::b:apple:: <!-- fab fa-apple -->
+::fab:apple:: <!-- fab fa-apple -->
+::fa-brands:apple:: <!-- fa-brands fa-apple -->
 
-<VPIcon icon="r:heart" /> <!-- far fa-heart -->
-<VPIcon icon="far:heart" /> <!-- far fa-heart -->
-<VPIcon icon="fa-regular:heart" /> <!-- fa-regular fa-heart -->
+::r:heart:: <!-- far fa-heart -->
+::far:heart:: <!-- far fa-heart -->
+::fa-regular:heart:: <!-- fa-regular fa-heart -->
 ```
 
 You can add other classes that fontawesome supports after the icon name and split them with a space, where `fa-` prefix is optional:
 
 ```md
 <!-- a small size icon -->
 
-<VPIcon icon="home fa-sm" /> <!-- fas fa-home fa-sm -->
+::home fa-sm:: <!-- fas fa-home fa-sm -->
 
 <!-- rotate 180deg -->
 
-<VPIcon icon="home rotate-180" /> <!-- fas fa-home fa-rotate-180 -->
+::home rotate-180:: <!-- fas fa-home fa-rotate-180 -->
 ```
 
 See <https://docs.fontawesome.com/web/style/styling> for all available classes.
@@ -166,16 +193,13 @@ Images links are supported with any icon types (relative links are NOT supported
 
 ```md
 <!-- A full link -->
-<VPIcon icon="https://example.com/icon.png" />
 
-<!-- icon.png should be placed in .vuepress/public folder -->
-<VPIcon icon="/icon.png" />
-```
+::https://example.com/icon.png::
 
-## Demo
+<!-- icon.png should be placed in .vuepress/public folder -->
 
-- <VPIcon icon="mdi:home" color="blue" />: home icon
-- <VPIcon icon="mdi:apple" size="2rem" vertical-align="text-bottom" />: apple icon
+<VPIcon icon="/icon.png" /> <!-- ::/icon.png:: is NOT supported as it will be parsed as color -->
+```
 
 ## Options
 
@@ -248,9 +272,17 @@ Images links are supported with any icon types (relative links are NOT supported
 
   Name of the icon component. If set to `null`, the plugin will not register the icon component globally.
 
+### markdown
+
+- Type: `boolean`
+- Default: `true`
+- Details:
+
+  Whether to enable icon syntax (`::icon::`) in markdown.
+
 ## Component Props
 
-### icon
+### icon {#icon-prop}
 
 - Type: `string`
 - Required: Yes

docs/zh/plugins/features/icon.md

@@ -26,16 +26,43 @@ export default {
 }
 ```
 
-我们还支持多种类型的图标：
+我们支持多种类型的图标：
 
 - `iconify`（默认）
 - `fontawesome`
 - `iconfont`
 
-另外，图标类型支持任何图像链接（不支持相对链接）。
+此外，你也可以使用任何图像链接作为图标（不支持相对链接）。
 
 如果你想要一个新的图标类型，请提交一个议题或提交 PR。
 
+在 Markdown 中，你可以使用 `::icon decorators... =size /color key=value complex-key="complex value"...::` 插入自定义图标。
+
+- 以 `=` 开头的字符串将被视为尺寸定义。
+- 以 `/` 开头的字符串将被视为颜色定义。
+- 任何本身是有效 html 属性的字符串将被解析、标准化并添加到图标元素中。
+- 其余部分将被视为图标名称。
+
+```md
+::icon =16 /red:: <!-- <VPIcon class="icon" color="red" size="16px" -->
+
+::icon rotate vertical-align=middle:: <!-- ::icon rotate" vertical-align="middle" -->
+```
+
+::: info 案例
+
+::mdi:home /blue::
+::mdi:apple =2rem vertical-align=text-bottom::
+
+```md
+::mdi:home /blue::
+::mdi:apple =2rem vertical-align=text-bottom::
+```
+
+:::
+
+## 图标类型
+
 ### Iconify
 
 有关完整的图标列表，请参见 <https://icon-sets.iconify.design/>。要使用图标，请复制选择器中的 `iconify-icon` 的图标名称。
@@ -50,8 +77,8 @@ export default {
 如果你主要使用 1 个图标集，可以将前缀设置为图标集名称（例如：`mdi:`），然后你可以使用图标名称而无需前缀。手动声明完整图标名称将覆盖前缀：
 
 ```md
-<VPIcon icon="home" /> <!-- mdi:home -->
-<VPIcon icon="svg-spinners:180-ring" /> <!-- svg-spinners:180-ring -->
+::home:: <!-- mdi:home -->
+::svg-spinners:180-ring:: <!-- svg-spinners:180-ring -->
 ```
 
 ### Font Awesome
@@ -63,38 +90,38 @@ export default {
 实心图标可以直接使用。如果要使用常规或品牌图标，则需要在图标名称前添加 `regular:` 或 `brands:` 前缀：
 
 ```md
-<VPIcon icon="home" /> <!-- fas fa-home (实心是默认的) -->
-<VPIcon icon="solid:home" /> <!-- fas fa-home -->
-<VPIcon icon="regular:heart" /> <!-- far fa-heart -->
-<VPIcon icon="brands:apple" /> <!-- fab fa-apple -->
+::home:: <!-- fas fa-home (实心是默认的) -->
+::solid:home:: <!-- fas fa-home -->
+::regular:heart:: <!-- far fa-heart -->
+::brands:apple:: <!-- fab fa-apple -->
 ```
 
 此外，还支持三个字母前缀、第一个字母或完整类名：
 
 ```md
-<VPIcon icon="s:home" /> <!-- fas fa-home -->
-<VPIcon icon="fas:home" /> <!-- fas fa-home -->
-<VPIcon icon="fa-solid:home" /> <!-- fa-solid fa-home -->
+::s:home:: <!-- fas fa-home -->
+::fas:home:: <!-- fas fa-home -->
+::fa-solid:home:: <!-- fa-solid fa-home -->
 
-<VPIcon icon="b:apple" /> <!-- fab fa-apple -->
-<VPIcon icon="fab:apple" /> <!-- fab fa-apple -->
-<VPIcon icon="fa-brands:apple" /> <!-- fa-brands fa-apple -->
+::b:apple:: <!-- fab fa-apple -->
+::fab:apple:: <!-- fab fa-apple -->
+::fa-brands:apple:: <!-- fa-brands fa-apple -->
 
-<VPIcon icon="r:heart" /> <!-- far fa-heart -->
-<VPIcon icon="far:heart" /> <!-- far fa-heart -->
-<VPIcon icon="fa-regular:heart" /> <!-- fa-regular fa-heart -->
+::r:heart:: <!-- far fa-heart -->
+::far:heart:: <!-- far fa-heart -->
+::fa-regular:heart:: <!-- fa-regular fa-heart -->
 ```
 
 你可以在图标名称后添加其他 fontawesome 支持的类，并用空格分隔，其中 `fa-` 前缀是可选的：
 
 ```md
 <!-- 一个小尺寸 icon -->
 
-<VPIcon icon="home fa-sm" /> <!-- fas fa-home fa-sm -->
+::home fa-sm:: <!-- fas fa-home fa-sm -->
 
 <!-- 旋转 180° -->
 
-<VPIcon icon="home rotate-180" /> <!-- fas fa-home fa-rotate-180 -->
+::home rotate-180:: <!-- fas fa-home fa-rotate-180 -->
 ```
 
 有关所有可用类的详细信息，请参见 <https://docs.fontawesome.com/web/style/styling>。
@@ -166,16 +193,13 @@ export default {
 
 ```md
 <!-- 完整链接 -->
-<VPIcon icon="https://example.com/icon.png" />
 
-<!-- icon.png 应该放在 .vuepress/public 文件夹中 -->
-<VPIcon icon="/icon.png" />
-```
+::https://example.com/icon.png::
 
-## 案例
+<!-- icon.png 应该放在 .vuepress/public 文件夹中 -->
 
-- <VPIcon icon="mdi:home" color="blue" />: 家图标
-- <VPIcon icon="mdi:apple" size="2rem" vertical-align="text-bottom" />: 苹果图标
+<VPIcon icon="/icon.png" /> <!-- ::/icon.png:: 是不被支持的，因为它会被解析为颜色 -->
+```
 
 ## 选项
 
@@ -249,7 +273,7 @@ export default {
 
 ## 组件属性
 
-### icon
+### icon {#icon-prop}
 
 - 类型：`string`
 - 必填： 是

plugins/features/plugin-icon/package.json

@@ -41,6 +41,7 @@
     "style": "sass src:lib --embed-sources --style=compressed"
   },
   "dependencies": {
+    "@mdit/plugin-icon": "^0.16.5",
     "@vuepress/helper": "workspace:*",
     "@vueuse/core": "^12.4.0",
     "vue": "^3.5.13"

plugins/features/plugin-icon/src/node/iconPlugin.ts

@@ -1,3 +1,4 @@
+import { extractInfo, icon, stringifyAttrs } from '@mdit/plugin-icon'
 import { addCustomElement, addViteSsrNoExternal } from '@vuepress/helper'
 import type { Plugin } from 'vuepress/core'
 
@@ -19,6 +20,23 @@ export const iconPlugin = (options: IconPluginOptions = {}): Plugin => {
         addCustomElement(bundlerOptions, app, 'iconify-icon')
     },
 
+    extendsMarkdown: (md): void => {
+      if (options.markdown !== false) {
+        md.use(icon, {
+          render: (raw) => {
+            const { attrs, content, color, size } = extractInfo({
+              content: raw,
+            })
+
+            if (color && !attrs.color) attrs.color = color
+            if (size && !attrs.size) attrs.size = size
+
+            return `<${options.component ?? 'VPIcon'} icon="${content}"${stringifyAttrs(attrs)} />`
+          },
+        })
+      }
+    },
+
     clientConfigFile: (app) => prepareConfigFile(app, options, iconType),
   }
 }

plugins/features/plugin-icon/src/node/options.ts

@@ -46,4 +46,13 @@ export interface IconPluginOptions {
    * @default "VPIcon"
    */
   component?: string
+
+  /**
+   * Enable markdown syntax
+   *
+   * 启用 Markdown 语法
+   *
+   * @default true
+   */
+  markdown?: boolean
 }