feat(md-enhance): add stylize option (#1895)

Co-authored-by: 史荣久 <trydofor@gmail.com>

docs/md-enhance/src/config.md

@@ -237,6 +237,52 @@ Whether to enable flowchart support
 
 Whether to enable [Mermaid](https://mermaid-js.github.io/mermaid/#/) support.
 
+## stylize
+
+- Type: `StylizeOptions | false`
+
+  ```ts
+  interface StylizeResult {
+    /**
+     * Tag name
+     */
+    tag: string;
+
+    /**
+     * Attributes settings
+     */
+    attrs: Record<string, string>;
+
+    /**
+     * Tag content
+     */
+    content: string;
+  }
+
+  interface StylizeItem {
+    /**
+     * Inline token matcher
+     */
+    matcher: string | RegExp;
+
+    /**
+     * Content Replacer
+     */
+    replacer: (options: {
+      tag: string;
+      content: string;
+      attrs: Record<string, string>;
+      env?: MarkdownEnv;
+    }) => StylizeResult | void;
+  }
+
+  type StylizeOptions = StylizeItem[];
+  ```
+
+- Default: `false`
+
+Stylize inline tokens to create snippet you want.
+
 ## demo
 
 - Type: `CodeDemoGlobalOptions | boolean`

docs/md-enhance/src/guide/README.md

@@ -266,3 +266,9 @@ $$
 @slideend
 
 - [View Detail](presentation/README.md)
+
+## Stylize
+
+Setting this to a invliad stytax <span style="color:red">doesn't</span> have any effect.
+
+- [View Detail](stylize.md)

docs/md-enhance/src/guide/stylize.md

@@ -0,0 +1,190 @@
+---
+title: Stylize
+icon: style
+---
+
+This plugin can stylize inline tokens including changing tags, adding attributes and modifying content.
+
+It's useful for you to create inline snippet with it.
+
+<!-- more -->
+
+## Config
+
+::: code-tabs#language
+
+@tab TS
+
+```ts
+// .vuepress/config.ts
+import { mdEnhance } from "vuepress-plugin-md-enhance";
+
+export default {
+  plugins: [
+    mdEnhance({
+      stylize: [
+        // options here
+      ],
+    }),
+  ],
+};
+```
+
+@tab JS
+
+```js
+// .vuepress/config.js
+const { mdEnhance } = require("vuepress-plugin-md-enhance");
+
+module.exports = {
+  plugins: [
+    mdEnhance({
+      stylize: [
+        // options here
+      ],
+    }),
+  ],
+};
+```
+
+:::
+
+## Usage
+
+The `stylize` receives an array, where each element accepts 2 options:
+
+- `matcher`: should be `string` or `RegExp`.
+
+- `replacer`: a function cutomizing the matched token
+
+For example, you can use the following cofig to transform `*Recommanded*` into a Badge `<Badge type="tip">Recommanded</Badge>`:
+
+::: code-tabs#language
+
+@tab TS
+
+```ts
+// .vuepress/config.ts
+import { mdEnhance } from "vuepress-plugin-md-enhance";
+
+export default {
+  plugins: [
+    mdEnhance({
+      stylize: [
+        {
+          match: "Recommanded",
+          replacer: ({ tag, attrs }) => {
+            if (tag === "em")
+              return {
+                tag: "Badge",
+                attrs: { type: "tip" },
+                content: "Recommanded",
+              };
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+@tab JS
+
+```js
+// .vuepress/config.js
+const { mdEnhance } = require("vuepress-plugin-md-enhance");
+
+module.exports = {
+  plugins: [
+    mdEnhance({
+      stylize: [
+        {
+          match: "Recommanded",
+          replacer: ({ tag, attrs }) => {
+            if (tag === "em")
+              return {
+                tag: "Badge",
+                attrs: { type: "tip" },
+                content: "Recommanded",
+              };
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+:::
+
+Another example is you want a to set all the emphsis `n't` words to red color, so that `Setting this to a invliad stytax *doesn't* have any effect.` becomes: "Setting this to a invliad stytax <span style="color:red">doesn't</span> have any effect."
+
+::: code-tabs#language
+
+@tab TS
+
+```ts
+// .vuepress/config.ts
+import { mdEnhance } from "vuepress-plugin-md-enhance";
+
+export default {
+  plugins: [
+    mdEnhance({
+      stylize: [
+        {
+          match: /n't$/,
+          replacer: ({ tag, attrs, content }) => {
+            if (tag === "em")
+              return {
+                tag: "span",
+                attrs: { style: "color: red" },
+                content,
+              };
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+@tab JS
+
+```js
+// .vuepress/config.js
+const { mdEnhance } = require("vuepress-plugin-md-enhance");
+
+module.exports = {
+  plugins: [
+    mdEnhance({
+      stylize: [
+        {
+          match: /n't$/,
+          replacer: ({ tag, attrs, content }) => {
+            if (tag === "em")
+              return {
+                tag: "span",
+                attrs: { style: "color: red" },
+                content,
+              };
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+:::
+
+If you want to skip some words in some pages, you can set `noStylize` in page frontmatter with an array containing content you don't want to stylize.
+
+::: info Performance
+
+To avoid preformance impact, you should try to avoid using RegExp for better performance unless you need it.
+
+Also try to create snippets with RegExp having lower costs, e.g: RegExp starting with `^` and ending with `$`.
+
+For example, if you only want to match "SHOULD", "MUST" and "MAY", you should write `/^(?:SHOULD|M(?:UST|AY))$/u` instead of `/SHOULD|MUST|MAY/u`. The fist one will only match 2 time with "A loo...oong content" with 1000 characters, but will match nearly 3000 times with the second RegExp.
+
+:::

docs/md-enhance/src/zh/config.md

@@ -237,6 +237,52 @@ interface TaskListOptions {
 
 是否启用 [Mermaid](https://mermaid-js.github.io/mermaid/#/) 支持。
 
+## stylize
+
+- 类型: `StylizeOptions | false`
+
+  ```ts
+  interface StylizeResult {
+    /**
+     * 渲染的标签名称
+     */
+    tag: string;
+
+    /**
+     * 属性设置
+     */
+    attrs: Record<string, string>;
+
+    /**
+     * 标签内容
+     */
+    content: string;
+  }
+
+  interface StylizeItem {
+    /**
+     * 字符匹配
+     */
+    matcher: string | RegExp;
+
+    /**
+     * 内容替换
+     */
+    replacer: (options: {
+      tag: string;
+      content: string;
+      attrs: Record<string, string>;
+      env?: MarkdownEnv;
+    }) => StylizeResult | void;
+  }
+
+  type StylizeOptions = StylizeItem[];
+  ```
+
+- 默认值: `false`
+
+对行内语法进行样式化以创建代码片段
+
 ## demo
 
 - 类型: `CodeDemoGlobalOptions | boolean`

docs/md-enhance/src/zh/guide/README.md

@@ -264,3 +264,9 @@ $$
 @slideend
 
 - [查看详情](presentation/README.md)
+
+## 样式化
+
+设置它<span style="color:red">没有</span>任何效果，请<span style="color:red">不要</span>这样使用
+
+- [查看详情](stylize.md)