feat(plugin-md-power): add markdown env presets, #815 (#818)

docs/.vuepress/collections/en/theme-guide.ts

@@ -67,6 +67,7 @@ export const themeGuide: ThemeCollectionItem = defineCollection({
             'caniuse',
             'chat',
             'include',
+            'env',
           ],
         },
         {

docs/.vuepress/collections/zh/theme-guide.ts

@@ -67,6 +67,7 @@ export const themeGuide: ThemeCollectionItem = defineCollection({
             'caniuse',
             'chat',
             'include',
+            'env',
           ],
         },
         {

docs/en/guide/markdown/abbr.md

@@ -54,3 +54,52 @@ The HTML specification is maintained by the W3C.
 ::: warning
 Abbreviations should be independent words or phrases. For Chinese abbreviations, add spaces on both sides of the word to distinguish them.
 :::
+
+## Global Presets
+
+For convenience, commonly used abbreviations can be preset in the configuration to avoid repeatedly
+defining abbreviations in each markdown file.
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      // [!code ++:4]
+      abbr: {
+        W3C: 'World Wide Web Consortium',
+        ECMA: 'European Computer Manufacturers Association'
+      },
+    }
+  })
+})
+```
+
+It can also be achieved by configuring the `abbreviations` option in `markdown.env`.
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      env: {
+        // [!code ++:4]
+        abbreviations: {
+          W3C: 'World Wide Web Consortium',
+          ECMA: 'European Computer Manufacturers Association'
+        }
+      }
+    }
+  })
+})
+```
+
+Globally preset abbreviations can be used in any markdown file.
+
+**Input：**
+
+```md
+The HTML specification is maintained by the W3C.
+```
+
+**Output：**
+
+The HTML specification is maintained by the W3C.

docs/en/guide/markdown/annotation.md

@@ -152,3 +152,59 @@ The ancient Chinese **Four Great Classical Novels** [+novels] are household name
 
   Depicts the story of 108 outlaws, led by Song Jiang, who gather at Liangshan Marsh during the late
   Northern Song Dynasty to rebel against the imperial government, showcasing the social reality of oppression leading to rebellion.
+
+## Global Presets
+
+For convenience, commonly used content annotations can be preset in the configuration to avoid repetitive definitions in each markdown file.
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      annotation: {
+        vuepress: 'VuePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG).It is specifically designed for building fast, content-centric sites.',
+        novels: [
+          '**"Romance of the Three Kingdoms":**\nSet against the backdrop of the Three Kingdoms period in Chinese history, it depicts the political and military struggles between the states of Wei, Shu, and Wu, shaping the images of numerous historical figures such as Zhuge Liang, Cao Cao, Guan Yu, and Liu Bei.',
+          '**"Journey to the West":**\nTells the story of the monk Xuanzang and his three disciples (Sun Wukong, Zhu Bajie, Sha Wujing, and the White Dragon Horse) on their journey to the West to obtain sacred Buddhist texts, filled with mythological elements and fantastical adventures.',
+          '**"Dream of the Red Chamber":**\nSet against the backdrop of the decline of the four major families Jia, Shi, Wang, and Xue, it depicts the love tragedy between Jia Baoyu, Lin Daiyu, and Xue Baochai, revealing the corruption and decay of feudal society.',
+          '**"Water Margin":**\nDepicts the story of 108 outlaws, led by Song Jiang, who gather at Liangshan Marsh during the late Northern Song Dynasty to rebel against the imperial government, showcasing the social reality of oppression leading to rebellion.'
+        ],
+      }
+    }
+  })
+})
+```
+
+It can also be achieved by configuring the `annotations` option in `markdown.env`.
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      env: {
+        annotations: {
+          vuepress: 'VuePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG).It is specifically designed for building fast, content-centric sites.',
+          novels: [
+            '**"Romance of the Three Kingdoms":**\nSet against the backdrop of the Three Kingdoms period in Chinese history, it depicts the political and military struggles between the states of Wei, Shu, and Wu, shaping the images of numerous historical figures such as Zhuge Liang, Cao Cao, Guan Yu, and Liu Bei.',
+            '**"Journey to the West":**\nTells the story of the monk Xuanzang and his three disciples (Sun Wukong, Zhu Bajie, Sha Wujing, and the White Dragon Horse) on their journey to the West to obtain sacred Buddhist texts, filled with mythological elements and fantastical adventures.',
+            '**"Dream of the Red Chamber":**\nSet against the backdrop of the decline of the four major families Jia, Shi, Wang, and Xue, it depicts the love tragedy between Jia Baoyu, Lin Daiyu, and Xue Baochai, revealing the corruption and decay of feudal society.',
+            '**"Water Margin":**\nDepicts the story of 108 outlaws, led by Song Jiang, who gather at Liangshan Marsh during the late Northern Song Dynasty to rebel against the imperial government, showcasing the social reality of oppression leading to rebellion.'
+          ],
+        }
+      }
+    }
+  })
+})
+```
+
+Globally preset content annotations can be used in any markdown file.
+
+**Input:**
+
+```md
+The ancient Chinese **Four Great Classical Novels** [+novels] are household names.
+```
+
+**Output:**
+
+The ancient Chinese **Four Great Classical Novels** [+novels] are household names.

docs/en/guide/markdown/env.md

@@ -0,0 +1,98 @@
+---
+title: Environment preset
+icon: eos-icons:env
+createTime: 2026/01/13 22:21:56
+permalink: /en/guide/markdown/env/
+---
+
+## Overview
+
+Environment presets (`markdown.env`) can be used to configure preset values for the Markdown rendering environment,
+
+such as reference links, content annotations, abbreviations, etc., thereby avoiding repetitive definitions in each Markdown file.
+
+**Environment presets can take effect in any Markdown file.**
+
+## Configuration
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      env: {
+        // reference
+        references: {
+          vuepress: 'https://v2.vuepress.vuejs.org/'
+        },
+        // abbreviation
+        abbreviations: {
+          HTML: 'Hypertext Markup Language'
+        },
+        // annotation
+        annotations: {
+          vuepress: 'VuePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG).It is specifically designed for building fast, content-centric sites.'
+        }
+      }
+    }
+  })
+})
+```
+
+The above configuration is equivalent to including the following in any markdown file:
+
+```md
+[vuepress]: https://v2.vuepress.vuejs.org/
+
+*[HTML]: Hypertext Markup Language
+
+[+vuepress]: VuePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG).It is specifically designed for building fast, content-centric sites.
+```
+
+Therefore, these environment presets can be used in any markdown file:
+
+```md
+Link reference: [vuepress][vuepress]
+
+Abbreviation: HTML
+
+Content note: vuepress [+vuepress]
+```
+
+Link reference: [vuepress][vuepress]
+
+Abbreviation: HTML
+
+Content note: vuepress [+vuepress]
+
+[vuepress]: https://v2.vuepress.vuejs.org/
+
+*[HTML]: Hypertext Markup Language
+
+[+vuepress]:
+  VuePress is a [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG).
+  It is specifically designed for building fast, content-centric sites.
+
+## Interface
+
+```ts
+interface MarkdownEnvPreset {
+  /**
+   * Reference links
+   */
+  references?: {
+    [label: string]: string | { title?: string, href: string }
+  }
+  /**
+   * Abbreviation
+   */
+  abbreviations?: {
+    [label: string]: string
+  }
+  /**
+   * Annotation
+   */
+  annotations?: {
+    [label: string]: string | string[]
+  }
+}
+```

docs/guide/markdown/abbr.md

@@ -52,3 +52,51 @@ The HTML specification is maintained by the W3C.
 
 ::: warning 缩写词应该是独立的单词或词组。对于中文的缩写词，应该在词的左右加空格以区分。
 :::
+
+## 全局预设
+
+为了方便使用，可以在配置中预设一些常用的缩写词，从而避免在每个 markdown 文件中重复定义缩写词。
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      // [!code ++:4]
+      abbr: {
+        W3C: 'World Wide Web Consortium',
+        ECMA: 'European Computer Manufacturers Association'
+      },
+    }
+  })
+})
+```
+
+也可以通过 `markdown.env` 配置 `abbreviations` 选项来实现。
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      env: {
+        // [!code ++:4]
+        abbreviations: {
+          W3C: 'World Wide Web Consortium',
+          ECMA: 'European Computer Manufacturers Association'
+        }
+      }
+    }
+  })
+})
+```
+
+全局预设的缩写词可以在任何 markdown 文件中使用。
+
+**输入：**
+
+```md
+The HTML specification is maintained by the W3C.
+```
+
+**输出：**
+
+The HTML specification is maintained by the W3C.

docs/guide/markdown/annotation.md

@@ -144,3 +144,59 @@ export default defineUserConfig({
   **《水浒传》：**
 
   描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。
+
+## 全局预设
+
+为了方便使用，可以在配置中预设一些常用的内容注释，从而避免在每个 markdown 文件中重复定义。
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      annotation: {
+        vuepress: 'VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。',
+        名著: [
+          '**《三国演义》：**\n以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争，塑造了诸葛亮、曹操、关羽、刘备等众多历史人物形象。',
+          '**《西游记》：**\n讲述了唐僧师徒四人（孙悟空、猪八戒、沙僧、白龙马）西天取经的故事，充满了神话色彩和奇幻冒险。',
+          '**《红楼梦》：**\n以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉、薛宝钗等人的爱情悲剧，展现了封建社会的腐朽与没落。',
+          '**《水浒传》：**\n描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。',
+        ],
+      }
+    }
+  })
+})
+```
+
+也可以通过 `markdown.env` 配置 `annotations` 选项来实现。
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      env: {
+        annotations: {
+          vuepress: 'VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。',
+          名著: [
+            '**《三国演义》：**\n以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争，塑造了诸葛亮、曹操、关羽、刘备等众多历史人物形象。',
+            '**《西游记》：**\n讲述了唐僧师徒四人（孙悟空、猪八戒、沙僧、白龙马）西天取经的故事，充满了神话色彩和奇幻冒险。',
+            '**《红楼梦》：**\n以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉、薛宝钗等人的爱情悲剧，展现了封建社会的腐朽与没落。',
+            '**《水浒传》：**\n描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。',
+          ],
+        }
+      }
+    }
+  })
+})
+```
+
+全局预设的内容注释可以在任何 markdown 文件中使用。
+
+**输入：**
+
+```md
+中国古代 **四大名著** [+名著] 家喻户晓。
+```
+
+**输出：**
+
+中国古代 **四大名著** [+名著] 家喻户晓。

docs/guide/markdown/env.md

@@ -0,0 +1,95 @@
+---
+title: 环境预设
+icon: eos-icons:env
+createTime: 2026/01/13 17:59:06
+permalink: /guide/markdown/env/
+---
+
+## 概述
+
+环境预设 (`markdown.env`) 可以用来配置一些 Markdown 渲染环境的预设值，
+比如 引用链接、内容注释、缩写词等，从而避免在每个 markdown 文件中重复定义。
+
+**环境预设在 任意 markdown 文件中都可以生效。**
+
+## 配置
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    markdown: {
+      env: {
+        // 引用链接
+        references: {
+          vuepress: 'https://v2.vuepress.vuejs.org/'
+        },
+        // 缩写词
+        abbreviations: {
+          HTML: 'Hypertext Markup Language'
+        },
+        // 内容注释
+        annotations: {
+          vuepress: 'VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。'
+        }
+      }
+    }
+  })
+})
+```
+
+以上配置等同于在 任意 markdown 文件中：
+
+```md
+[vuepress]: https://v2.vuepress.vuejs.org/
+
+*[HTML]: Hypertext Markup Language
+
+[+vuepress]: VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。
+```
+
+因此，可以在任意 markdown 文件中使用这些环境预设：
+
+```md
+链接引用：[vuepress][vuepress]
+
+缩写词：HTML
+
+内容注释：vuepress [+vuepress]
+```
+
+链接引用：[vuepress][vuepress]
+
+缩写词：HTML
+
+内容注释：vuepress [+vuepress]
+
+[vuepress]: https://v2.vuepress.vuejs.org/
+
+*[HTML]: Hypertext Markup Language
+
+[+vuepress]: VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。
+
+## Interface
+
+```ts
+interface MarkdownEnvPreset {
+  /**
+   * 引用链接
+   */
+  references?: {
+    [label: string]: string | { title?: string, href: string }
+  }
+  /**
+   * 缩写词
+   */
+  abbreviations?: {
+    [label: string]: string
+  }
+  /**
+   * 内容注释
+   */
+  annotations?: {
+    [label: string]: string | string[]
+  }
+}
+```

plugins/plugin-md-power/src/client/components/Abbreviation.vue

@@ -93,7 +93,7 @@ watch(show, () => nextTick(() => {
   position: absolute;
   top: calc(100% + 12px);
   left: 50%;
-  z-index: 1;
+  z-index: 3;
   width: max-content;
   max-width: min(calc(100vw - 32px), 360px);
   padding: 8px 14px;

plugins/plugin-md-power/src/node/inline/abbr.ts

@@ -2,12 +2,13 @@
  * Forked and modified from https://github.com/markdown-it/markdown-it-abbr/blob/master/index.mjs
  */
 
-import type { PluginSimple } from 'markdown-it'
+import type { PluginWithOptions } from 'markdown-it'
 import type { RuleBlock } from 'markdown-it/lib/parser_block.mjs'
 import type { RuleCore } from 'markdown-it/lib/parser_core.mjs'
 import type StateBlock from 'markdown-it/lib/rules_block/state_block.mjs'
 import type StateCore from 'markdown-it/lib/rules_core/state_core.mjs'
 import type Token from 'markdown-it/lib/token.mjs'
+import { isEmptyObject, objectMap } from '@pengzhanbo/utils'
 import { cleanMarkdownEnv } from '../utils/cleanMarkdownEnv.js'
 
 interface AbbrStateBlock extends StateBlock {
@@ -22,9 +23,12 @@ interface AbbrStateCore extends StateCore {
   }
 }
 
-export const abbrPlugin: PluginSimple = (md) => {
+export const abbrPlugin: PluginWithOptions<Record<string, string>> = (md, globalAbbreviations = {}) => {
   const { arrayReplaceAt, escapeRE, lib } = md.utils
-
+  globalAbbreviations = objectMap(
+    globalAbbreviations,
+    (key, value) => [key.startsWith(':') ? key : `:${key}`, value],
+  )
   // ASCII characters in Cc, Sc, Sm, Sk categories we should terminate on;
   // you can check character classes here:
   // http://www.unicode.org/Public/UNIDATA/UnicodeData.txt
@@ -88,11 +92,12 @@ export const abbrPlugin: PluginSimple = (md) => {
 
   const abbrReplace: RuleCore = (state: AbbrStateCore) => {
     const tokens = state.tokens
-    const { abbreviations } = state.env
+    const { abbreviations: localAbbreviations } = state.env
 
-    if (!abbreviations)
+    if (!localAbbreviations && isEmptyObject(globalAbbreviations))
       return
 
+    const abbreviations = { ...globalAbbreviations, ...localAbbreviations }
     const abbreviationsRegExpText = Object.keys(abbreviations)
       .map(x => x.substring(1))
       .sort((a, b) => b.length - a.length)

plugins/plugin-md-power/src/node/inline/annotation.ts

@@ -1,9 +1,10 @@
-import type { PluginSimple } from 'markdown-it'
+import type { PluginWithOptions } from 'markdown-it'
 import type { RuleBlock } from 'markdown-it/lib/parser_block.mjs'
 import type { RuleInline } from 'markdown-it/lib/parser_inline.mjs'
 import type StateBlock from 'markdown-it/lib/rules_block/state_block.mjs'
 import type StateInline from 'markdown-it/lib/rules_inline/state_inline.mjs'
 import type Token from 'markdown-it/lib/token.mjs'
+import { objectMap, toArray } from '@pengzhanbo/utils'
 import { cleanMarkdownEnv } from '../utils/cleanMarkdownEnv'
 
 interface AnnotationToken extends Token {
@@ -154,7 +155,17 @@ const annotationRef: RuleInline = (
   return true
 }
 
-export const annotationPlugin: PluginSimple = (md) => {
+export const annotationPlugin: PluginWithOptions<Record<string, string | string[]>> = (
+  md,
+  globalAnnotations = {},
+) => {
+  const annotations = objectMap(globalAnnotations, (key, value) => {
+    return [
+      key.startsWith(':') ? key : `:${key}`,
+      { sources: toArray(value), rendered: [] },
+    ]
+  })
+
   md.renderer.rules.annotation_ref = (
     tokens: AnnotationToken[],
     idx: number,
@@ -162,7 +173,7 @@ export const annotationPlugin: PluginSimple = (md) => {
     env: AnnotationEnv,
   ) => {
     const label = tokens[idx].meta.label
-    const data = env.annotations[`:${label}`]
+    const data = env.annotations[`:${label}`] || annotations[`:${label}`]
 
     return `<Annotation label="${label}" :total="${data.sources.length}">${
       data.sources.map((source, i) => {

plugins/plugin-md-power/src/node/inline/env-preset.ts

@@ -0,0 +1,35 @@
+import type { PluginWithOptions } from 'markdown-it'
+import type { MarkdownEnvPreset } from '../../shared/index.js'
+import { isEmptyObject, isString, objectMap } from '@pengzhanbo/utils'
+
+/**
+ * inject preset to markdown env
+ */
+export const envPresetPlugin: PluginWithOptions<MarkdownEnvPreset> = (md, env = {}) => {
+  if (isEmptyObject(env))
+    return
+
+  const references = objectMap(env.references || {}, (key, value) => {
+    return [md.utils.normalizeReference(key), isString(value) ? { href: value } : value]
+  })
+
+  const defaultRender = md.render
+  md.render = (source, env) => {
+    env ??= {}
+    env.references = {
+      ...references,
+      ...env.references,
+    }
+    return defaultRender(source, env)
+  }
+
+  const defaultRenderInline = md.renderInline
+  md.renderInline = (source, env) => {
+    env ??= {}
+    env.references = {
+      ...references,
+      ...env.references,
+    }
+    return defaultRenderInline(source, env)
+  }
+}

plugins/plugin-md-power/src/node/inline/index.ts

@@ -6,10 +6,11 @@ import { mark } from '@mdit/plugin-mark'
 import { sub } from '@mdit/plugin-sub'
 import { sup } from '@mdit/plugin-sup'
 import { tasklist } from '@mdit/plugin-tasklist'
-import { isPlainObject } from '@vuepress/helper'
+import { isPlainObject } from '@pengzhanbo/utils'
 import cjsFriendly from 'markdown-it-cjk-friendly'
 import { abbrPlugin } from './abbr.js'
 import { annotationPlugin } from './annotation.js'
+import { envPresetPlugin } from './env-preset.js'
 import { plotPlugin } from './plot.js'
 
 export function inlineSyntaxPlugin(
@@ -24,13 +25,20 @@ export function inlineSyntaxPlugin(
   md.use(footnote)
   md.use(tasklist)
 
+  const env = options.env || {}
+
+  envPresetPlugin(md, env)
+
   if (options.annotation) {
     /**
      * xxx [+foo] xxx
      *
      * [+foo]: xxx
      */
-    md.use(annotationPlugin)
+    md.use(annotationPlugin, {
+      ...env.annotations,
+      ...isPlainObject(options.annotation) ? options.annotation : {},
+    })
   }
 
   if (options.abbr) {
@@ -39,7 +47,10 @@ export function inlineSyntaxPlugin(
      *
      * [HTML]: A HTML element description
      */
-    md.use(abbrPlugin)
+    md.use(abbrPlugin, {
+      ...env.abbreviations,
+      ...isPlainObject(options.abbr) ? options.abbr : {},
+    })
   }
 
   // !!plot!!

plugins/plugin-md-power/src/shared/env.ts

@@ -0,0 +1,85 @@
+/* eslint-disable jsdoc/no-multi-asterisks */
+export interface MarkdownEnvPreset {
+  /**
+   * markdown reference preset, use in any markdown file
+   *
+   * markdown 引用链接预设，可在任何 markdown 文件中使用
+   *
+   * @see https://www.markdownguide.org/basic-syntax/#reference-style-links
+   *
+   * @example
+   * ```ts
+   * // config
+   * {
+   *   'label-1': 'http://example.com/',
+   *   'label-2': { href: 'http://example.com/', title: 'title' }
+   * }
+   * ```
+   * use `*.md`:
+   * ```markdown
+   * [link][label-1]
+   * [link][label-2]
+   * ```
+   * same as 等价于
+   * ```markdown
+   * [label-1]: http://example.com/
+   * [label-2]: http://example.com/ "title"
+   *
+   * [link][label-1]
+   * [link][label-2]
+   * ```
+   */
+  references?: Record<string, string | { title?: string, href: string }>
+  /**
+   * markdown abbreviation preset, use in any markdown file
+   *
+   * markdown 缩写词预设，可在任何 markdown 文件中使用
+   *
+   * @example
+   * ```ts
+   * // config
+   * {
+   *   'HTML': 'HyperText Markup Language',
+   *   'W3C': 'World Wide Web Consortium',
+   * }
+   * ```
+   * use `*.md`:
+   * ```markdown
+   * The HTML specification is maintained by the W3C.
+   * ```
+   * same as 等价于
+   * ```markdown
+   * *[HTML]: Hyper Text Markup Language
+   * *[W3C]: World Wide Web Consortium
+   *
+   * The HTML specification is maintained by the W3C.
+   * ```
+   */
+  abbreviations?: Record<string, string>
+  /**
+   * markdown annotation preset, use in any markdown file
+   *
+   * markdown 内容注释预设，可在任何 markdown 文件中使用
+   *
+   * @example
+   * ```ts
+   * // config
+   * {
+   *   'vuepress': 'vuepress is a Vue.js based documentation generator',
+   *   'vuepress-theme-plume': 'vuepress-theme-plume is a theme for vuepress',
+   * }
+   * ```
+   * use `*.md`:
+   * ```markdown
+   * [+vuepress-theme-plume] is a theme for [+vuepress]
+   * ```
+   * same as 等价于
+   * ```markdown
+   * [+vuepress]: vuepress is a Vue.js based documentation generator
+   * [+vuepress-theme-plume]: vuepress-theme-plume is a theme for vuepress
+   *
+   * [+vuepress-theme-plume] is a theme for [+vuepress]
+   * ```
+   */
+  annotations?: Record<string, string | string[]>
+}

plugins/plugin-md-power/src/shared/index.ts

@@ -3,6 +3,7 @@ export * from './codepen.js'
 export * from './codeSandbox.js'
 export * from './codeTabs.js'
 export * from './demo.js'
+export * from './env.js'
 export * from './fileTree.js'
 export * from './icon.js'
 export * from './jsfiddle.js'

plugins/plugin-md-power/src/shared/plugin.ts

@@ -1,6 +1,7 @@
 import type { CanIUseOptions } from './caniuse.js'
 import type { CodeTabsOptions } from './codeTabs.js'
 import type { CodeTreeOptions } from './codeTree.js'
+import type { MarkdownEnvPreset } from './env.js'
 import type { FileTreeOptions } from './fileTree.js'
 import type { IconOptions } from './icon.js'
 import type { MarkOptions } from './mark.js'
@@ -11,17 +12,44 @@ import type { ReplOptions } from './repl.js'
 import type { TableContainerOptions } from './table.js'
 
 export interface MarkdownPowerPluginOptions {
-  /**
-   * 是否启用注释
-   * @default false
-   */
-  annotation?: boolean
 
   /**
-   * 是否启用 abbr 语法
+   * 是否预设 markdown env，如 预设链接引用、缩写词、内容注释等
+   *
+   * 预设可以在任何 markdown 文件中使用
+   *
+   * @example
+   * ```ts
+   * env: {
+   *   references: {
+   *     vue: 'https://vuejs.org',
+   *   },
+   *   abbreviations: {
+   *     vue: 'Vue.js',
+   *   },
+   *   annotations: {
+   *     vue: 'Vue.js',
+   *   },
+   * }
+   * ```
+   * use `*.md`
+   * ```markdown
+   * [vue link][vue]
+   * vue is a framework, [+vue] is modern framework
+   * ```
+   */
+  env?: MarkdownEnvPreset
+  /**
+   * 是否启用注释， 或者预设内容注释
    * @default false
    */
-  abbr?: boolean
+  annotation?: boolean | MarkdownEnvPreset['annotations']
+
+  /**
+   * 是否启用 abbr 语法， 或者预设缩写词
+   * @default false
+   */
+  abbr?: boolean | MarkdownEnvPreset['abbreviations']
   /**
    * 马克笔动画模式
    * @default 'eager'

theme/src/node/detector/fields.ts

@@ -47,6 +47,7 @@ export const MARKDOWN_POWER_FIELDS: (keyof MarkdownPowerPluginOptions)[] = [
   'codeTree',
   'codepen',
   'demo',
+  'env',
   'fileTree',
   'field',
   'icons', // deprecated