vitepress-plugin-abbr 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pengzhanbo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# vitepress-plugin-abbr
+
+Add abbreviation support to your VitePress site, rendering abbreviations with an interactive tooltip
+that displays the full description on hover or focus.
+
+为 VitePress 添加缩写词支持，将缩写词渲染为可交互的提示框，在悬停或聚焦时显示其完整描述。
+
+Forked and modified from [`markdown-it-abbr`](https://github.com/markdown-it/markdown-it-abbr).
+
+## Usage
+
+### With Vitepress-tuck
+
+**Installation:**
+
+```bash
+# npm
+npm install -D vitepress-tuck vitepress-plugin-abbr
+# pnpm
+pnpm add -D vitepress-tuck vitepress-plugin-abbr
+# yarn
+yarn add -D vitepress-tuck vitepress-plugin-abbr
+```
+
+**Configuration:**
+
+```ts
+// .vitepress/config.ts
+import abbr from 'vitepress-plugin-abbr'
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  plugins: [abbr()],
+})
+```
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import enhanceApp from 'virtual:enhance-app'
+import DefaultTheme from 'vitepress/theme'
+import 'vitepress-plugin-abbr/style.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceApp(ctx)
+  },
+} satisfies Theme
+```
+
+### With Vitepress
+
+**Installation:**
+
+```bash
+# npm
+npm install -D vitepress-plugin-abbr
+# pnpm
+pnpm add -D vitepress-plugin-abbr
+# yarn
+yarn add -D vitepress-plugin-abbr
+```
+
+**Configuration:**
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress'
+import { abbrMarkdownPlugin } from 'vitepress-plugin-abbr'
+
+export default defineConfig({
+  markdown: {
+    config: (md) => {
+      md.use(abbrMarkdownPlugin)
+    },
+  },
+  vite: {
+    ssr: {
+      noExternal: ['vitepress-plugin-abbr'],
+    },
+  },
+})
+```
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import { VPAbbreviation } from 'vitepress-plugin-abbr/client'
+import DefaultTheme from 'vitepress/theme'
+import 'vitepress-plugin-abbr/style.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    ctx.app.component('VPAbbreviation', VPAbbreviation)
+  },
+} satisfies Theme
+```
+
+## Syntax
+
+Define an abbreviation with the `*[ABBR]: Full description` syntax, then use the abbreviation anywhere
+in your markdown content. The abbreviation text will be rendered with a dotted underline and a help cursor,
+and hovering or focusing it shows a tooltip with the full description.
+
+使用 `*[缩写]: 完整描述` 语法定义缩写词，然后在 markdown 内容的任意位置使用该缩写词。
+缩写词文本将渲染为带点状下划线和 help 鼠标样式的文本，悬停或聚焦时会显示包含完整描述的提示框。
+
+```md
+The HTML specification is maintained by the W3C.
+
+*[HTML]: HyperText Markup Language
+*[W3C]: World Wide Web Consortium
+```
+
+The description supports inline markdown, such as `**bold**`, `*italic*`, `[links](https://example.com)`, and `code`.
+
+描述支持内联 markdown 语法，例如 `**加粗**`、`*斜体*`、`[链接](https://example.com)` 和 `代码`。
+
+```md
+The **HTML** spec is maintained by the W3C.
+
+*[HTML]: HyperText Markup Language
+*[W3C]: World [Wide Web](https://www.w3.org/) Consortium
+```
+
+## Global Abbreviations
+
+Instead of (or in addition to) defining abbreviations inline in each markdown file,
+you can provide a global preset of abbreviations through the plugin options. Inline definitions take
+precedence over global ones when both define the same abbreviation.
+
+可以在每个 markdown 文件中内联定义缩写词，也可以通过插件选项提供全局缩写词预设
+当两者定义了相同的缩写词时，内联定义优先于全局定义。
+
+```ts
+// .vitepress/config.ts
+import abbr from 'vitepress-plugin-abbr'
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  plugins: [
+    abbr({
+      HTML: 'HyperText Markup Language',
+      W3C: 'World Wide Web Consortium',
+    }),
+  ],
+})
+```
+
+With the configuration above, every occurrence of `HTML` and `W3C` across all pages will be
+rendered as abbreviations automatically, without needing inline `*[...]:` definitions.
+
+配置上述内容后，所有页面中出现的 `HTML` 和 `W3C` 都会自动渲染为缩写词，无需逐个文件添加 `*[...]:` 内联定义。

package/dist/client/browser/index.d.ts

@@ -0,0 +1,47 @@
+import { EnhanceAppContext } from "vitepress/client";
+
+//#region src/client/VPAbbreviation.vue.d.ts
+declare var __VLS_1: {}, __VLS_21: {};
+type __VLS_Slots = {} & {
+  default?: (props: typeof __VLS_1) => any;
+} & {
+  tooltip?: (props: typeof __VLS_21) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/client/index.d.ts
+/**
+ * Enhances the VitePress application by registering the `VPAbbreviation`
+ * component globally under the name `Abbreviation`, so it can be used
+ * directly in Vue templates or rendered markdown content.
+ *
+ * 通过全局注册 `VPAbbreviation` 组件来增强 VitePress 应用，
+ * 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+ *
+ * @example
+ * `.vitepress/theme/index.ts`
+ * ```ts
+ * import type { Theme } from 'vitepress'
+ * import { enhanceAppWithAbbr } from 'vitepress-plugin-abbr/client'
+ * import DefaultTheme from 'vitepress/theme'
+ *
+ * export default {
+ *   extends: DefaultTheme,
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithAbbr(ctx)
+ *   },
+ * } satisfies Theme
+ * ```
+ */
+declare function enhanceAppWithAbbr({
+  app
+}: EnhanceAppContext): void;
+//#endregion
+export { _default as VPAbbreviation, enhanceAppWithAbbr };

package/dist/client/browser/index.js

@@ -0,0 +1,110 @@
+import "../style.css";
+import { Fragment, Teleport, Transition, createBlock, createElementBlock, createElementVNode, createVNode, defineComponent, mergeProps, normalizeStyle, openBlock, ref, renderSlot, resolveComponent, unref, useTemplateRef, vShow, withCtx, withDirectives } from "vue";
+import { arrow, autoUpdate, offset, shift, useFloating } from "@floating-ui/vue";
+//#region src/client/VPAbbreviation.vue
+const _sfc_main = /*@__PURE__*/ defineComponent({
+	inheritAttrs: false,
+	__name: "VPAbbreviation",
+	setup(__props) {
+		/**
+		* VPAbbreviation component for rendering abbreviations with an interactive
+		* tooltip in VitePress.
+		*
+		* VPAbbreviation 组件，用于在 VitePress 中渲染带有可交互提示框的缩写词。
+		*
+		* The abbreviation text is rendered as an underlined, help-cursor span. When
+		* the user hovers over or focuses the span, a floating tooltip anchored below
+		* the text is shown, displaying the full description provided via the
+		* `#tooltip` slot. The tooltip is teleported to `body` and positioned with
+		* `@floating-ui/vue`, applying offset, flip, shift, and arrow middleware for
+		* robust placement near viewport edges.
+		*
+		* 缩写词文本渲染为带下划线且鼠标为 help 样式的 span。当用户悬停或聚焦该
+		* span 时，会在文本下方显示一个浮动提示框，展示通过 `#tooltip` 插槽提供
+		* 的完整描述。提示框被传送到 `body`，并使用 `@floating-ui/vue` 定位，
+		* 应用 offset、flip、shift 和 arrow 中间件以保证在视口边缘附近的稳定定位。
+		*/
+		const abbr = useTemplateRef("abbr");
+		const tooltip = useTemplateRef("tooltip");
+		const tooltipArrow = useTemplateRef("tooltipArrow");
+		const show = ref(false);
+		const { floatingStyles, middlewareData } = useFloating(abbr, tooltip, {
+			whileElementsMounted: autoUpdate,
+			placement: "bottom",
+			middleware: [
+				offset(10),
+				shift({ padding: 20 }),
+				arrow({
+					element: tooltipArrow,
+					padding: 4
+				})
+			]
+		});
+		return (_ctx, _cache) => {
+			const _component_ClientOnly = resolveComponent("ClientOnly");
+			return openBlock(), createElementBlock(Fragment, null, [createElementVNode("span", mergeProps({
+				ref_key: "abbr",
+				ref: abbr,
+				class: "vp-abbr"
+			}, _ctx.$attrs, {
+				onMouseenter: _cache[0] || (_cache[0] = ($event) => show.value = true),
+				onMouseleave: _cache[1] || (_cache[1] = ($event) => show.value = false)
+			}), [renderSlot(_ctx.$slots, "default")], 16), createVNode(_component_ClientOnly, null, {
+				default: withCtx(() => [(openBlock(), createBlock(Teleport, { to: "body" }, [createVNode(Transition, {
+					name: "fade-in",
+					persisted: ""
+				}, {
+					default: withCtx(() => [withDirectives(createElementVNode("div", {
+						ref_key: "tooltip",
+						ref: tooltip,
+						role: "tooltip",
+						class: "vp-abbr-popover",
+						style: normalizeStyle(unref(floatingStyles)),
+						onMouseenter: _cache[2] || (_cache[2] = ($event) => show.value = true),
+						onMouseleave: _cache[3] || (_cache[3] = ($event) => show.value = false)
+					}, [createElementVNode("span", {
+						ref_key: "tooltipArrow",
+						ref: tooltipArrow,
+						class: "tooltip-arrow",
+						style: normalizeStyle({
+							left: unref(middlewareData).arrow?.x != null ? `${unref(middlewareData).arrow.x}px` : "",
+							top: unref(middlewareData).arrow?.y != null ? `${unref(middlewareData).arrow.y}px` : ""
+						})
+					}, null, 4), renderSlot(_ctx.$slots, "tooltip")], 36), [[vShow, show.value]])]),
+					_: 3
+				})]))]),
+				_: 3
+			})], 64);
+		};
+	}
+});
+//#endregion
+//#region src/client/index.ts
+/**
+* Enhances the VitePress application by registering the `VPAbbreviation`
+* component globally under the name `Abbreviation`, so it can be used
+* directly in Vue templates or rendered markdown content.
+*
+* 通过全局注册 `VPAbbreviation` 组件来增强 VitePress 应用，
+* 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+*
+* @example
+* `.vitepress/theme/index.ts`
+* ```ts
+* import type { Theme } from 'vitepress'
+* import { enhanceAppWithAbbr } from 'vitepress-plugin-abbr/client'
+* import DefaultTheme from 'vitepress/theme'
+*
+* export default {
+*   extends: DefaultTheme,
+*   enhanceApp(ctx) {
+*     enhanceAppWithAbbr(ctx)
+*   },
+* } satisfies Theme
+* ```
+*/
+function enhanceAppWithAbbr({ app }) {
+	app.component("VPAbbreviation", _sfc_main);
+}
+//#endregion
+export { _sfc_main as VPAbbreviation, enhanceAppWithAbbr };

package/dist/client/ssr/index.d.ts

@@ -0,0 +1,47 @@
+import { EnhanceAppContext } from "vitepress/client";
+
+//#region src/client/VPAbbreviation.vue.d.ts
+declare var __VLS_1: {}, __VLS_21: {};
+type __VLS_Slots = {} & {
+  default?: (props: typeof __VLS_1) => any;
+} & {
+  tooltip?: (props: typeof __VLS_21) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/client/index.d.ts
+/**
+ * Enhances the VitePress application by registering the `VPAbbreviation`
+ * component globally under the name `Abbreviation`, so it can be used
+ * directly in Vue templates or rendered markdown content.
+ *
+ * 通过全局注册 `VPAbbreviation` 组件来增强 VitePress 应用，
+ * 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+ *
+ * @example
+ * `.vitepress/theme/index.ts`
+ * ```ts
+ * import type { Theme } from 'vitepress'
+ * import { enhanceAppWithAbbr } from 'vitepress-plugin-abbr/client'
+ * import DefaultTheme from 'vitepress/theme'
+ *
+ * export default {
+ *   extends: DefaultTheme,
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithAbbr(ctx)
+ *   },
+ * } satisfies Theme
+ * ```
+ */
+declare function enhanceAppWithAbbr({
+  app
+}: EnhanceAppContext): void;
+//#endregion
+export { _default as VPAbbreviation, enhanceAppWithAbbr };

package/dist/client/ssr/index.js

@@ -0,0 +1,128 @@
+import { Teleport, Transition, createBlock, createVNode, defineComponent, mergeProps, openBlock, ref, renderSlot, resolveComponent, unref, useSSRContext, useTemplateRef, vShow, withCtx, withDirectives } from "vue";
+import { ssrRenderAttrs, ssrRenderComponent, ssrRenderSlot, ssrRenderStyle, ssrRenderTeleport } from "vue/server-renderer";
+import { arrow, autoUpdate, offset, shift, useFloating } from "@floating-ui/vue";
+//#region src/client/VPAbbreviation.vue
+const _sfc_main = /*@__PURE__*/ defineComponent({
+	inheritAttrs: false,
+	__name: "VPAbbreviation",
+	__ssrInlineRender: true,
+	setup(__props) {
+		/**
+		* VPAbbreviation component for rendering abbreviations with an interactive
+		* tooltip in VitePress.
+		*
+		* VPAbbreviation 组件，用于在 VitePress 中渲染带有可交互提示框的缩写词。
+		*
+		* The abbreviation text is rendered as an underlined, help-cursor span. When
+		* the user hovers over or focuses the span, a floating tooltip anchored below
+		* the text is shown, displaying the full description provided via the
+		* `#tooltip` slot. The tooltip is teleported to `body` and positioned with
+		* `@floating-ui/vue`, applying offset, flip, shift, and arrow middleware for
+		* robust placement near viewport edges.
+		*
+		* 缩写词文本渲染为带下划线且鼠标为 help 样式的 span。当用户悬停或聚焦该
+		* span 时，会在文本下方显示一个浮动提示框，展示通过 `#tooltip` 插槽提供
+		* 的完整描述。提示框被传送到 `body`，并使用 `@floating-ui/vue` 定位，
+		* 应用 offset、flip、shift 和 arrow 中间件以保证在视口边缘附近的稳定定位。
+		*/
+		const abbr = useTemplateRef("abbr");
+		const tooltip = useTemplateRef("tooltip");
+		const tooltipArrow = useTemplateRef("tooltipArrow");
+		const show = ref(false);
+		const { floatingStyles, middlewareData } = useFloating(abbr, tooltip, {
+			whileElementsMounted: autoUpdate,
+			placement: "bottom",
+			middleware: [
+				offset(10),
+				shift({ padding: 20 }),
+				arrow({
+					element: tooltipArrow,
+					padding: 4
+				})
+			]
+		});
+		return (_ctx, _push, _parent, _attrs) => {
+			const _component_ClientOnly = resolveComponent("ClientOnly");
+			_push(`<!--[--><span${ssrRenderAttrs(mergeProps({
+				ref_key: "abbr",
+				ref: abbr,
+				class: "vp-abbr"
+			}, _ctx.$attrs))}>`);
+			ssrRenderSlot(_ctx.$slots, "default", {}, null, _push, _parent);
+			_push(`</span>`);
+			_push(ssrRenderComponent(_component_ClientOnly, null, {
+				default: withCtx((_, _push, _parent, _scopeId) => {
+					if (_push) ssrRenderTeleport(_push, (_push) => {
+						_push(`<div role="tooltip" class="vp-abbr-popover" style="${ssrRenderStyle([unref(floatingStyles), show.value ? null : { display: "none" }])}"${_scopeId}><span class="tooltip-arrow" style="${ssrRenderStyle({
+							left: unref(middlewareData).arrow?.x != null ? `${unref(middlewareData).arrow.x}px` : "",
+							top: unref(middlewareData).arrow?.y != null ? `${unref(middlewareData).arrow.y}px` : ""
+						})}"${_scopeId}></span>`);
+						ssrRenderSlot(_ctx.$slots, "tooltip", {}, null, _push, _parent, _scopeId);
+						_push(`</div>`);
+					}, "body", false, _parent);
+					else return [(openBlock(), createBlock(Teleport, { to: "body" }, [createVNode(Transition, {
+						name: "fade-in",
+						persisted: ""
+					}, {
+						default: withCtx(() => [withDirectives(createVNode("div", {
+							ref_key: "tooltip",
+							ref: tooltip,
+							role: "tooltip",
+							class: "vp-abbr-popover",
+							style: unref(floatingStyles),
+							onMouseenter: ($event) => show.value = true,
+							onMouseleave: ($event) => show.value = false
+						}, [createVNode("span", {
+							ref_key: "tooltipArrow",
+							ref: tooltipArrow,
+							class: "tooltip-arrow",
+							style: {
+								left: unref(middlewareData).arrow?.x != null ? `${unref(middlewareData).arrow.x}px` : "",
+								top: unref(middlewareData).arrow?.y != null ? `${unref(middlewareData).arrow.y}px` : ""
+							}
+						}, null, 4), renderSlot(_ctx.$slots, "tooltip")], 44, ["onMouseenter", "onMouseleave"]), [[vShow, show.value]])]),
+						_: 3
+					})]))];
+				}),
+				_: 3
+			}, _parent));
+			_push(`<!--]-->`);
+		};
+	}
+});
+const _sfc_setup = _sfc_main.setup;
+_sfc_main.setup = (props, ctx) => {
+	const ssrContext = useSSRContext();
+	(ssrContext.modules || (ssrContext.modules = /* @__PURE__ */ new Set())).add("src/client/VPAbbreviation.vue");
+	return _sfc_setup ? _sfc_setup(props, ctx) : void 0;
+};
+//#endregion
+//#region src/client/index.ts
+/**
+* Enhances the VitePress application by registering the `VPAbbreviation`
+* component globally under the name `Abbreviation`, so it can be used
+* directly in Vue templates or rendered markdown content.
+*
+* 通过全局注册 `VPAbbreviation` 组件来增强 VitePress 应用，
+* 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+*
+* @example
+* `.vitepress/theme/index.ts`
+* ```ts
+* import type { Theme } from 'vitepress'
+* import { enhanceAppWithAbbr } from 'vitepress-plugin-abbr/client'
+* import DefaultTheme from 'vitepress/theme'
+*
+* export default {
+*   extends: DefaultTheme,
+*   enhanceApp(ctx) {
+*     enhanceAppWithAbbr(ctx)
+*   },
+* } satisfies Theme
+* ```
+*/
+function enhanceAppWithAbbr({ app }) {
+	app.component("VPAbbreviation", _sfc_main);
+}
+//#endregion
+export { _sfc_main as VPAbbreviation, enhanceAppWithAbbr };

package/dist/client/style.css

@@ -0,0 +1,44 @@
+@import url("vitepress-plugin-toolkit/styles/transition/fade-in.css");
+
+.vp-abbr {
+  position: relative;
+  text-decoration: underline dotted currentcolor;
+  text-underline-offset: 4px;
+  cursor: help;
+}
+
+.vp-abbr-popover {
+  position: absolute;
+  width: max-content;
+  padding: 4px 8px;
+  font-size: 14px;
+  font-weight: bold;
+  color: var(--vp-c-text-1);
+  background-color: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 4px;
+  box-shadow: var(--vp-shadow-2);
+  transition: 0.25s ease-in-out;
+  transition-property: color, border-color, box-shadow;
+}
+
+.vp-abbr-popover .tooltip-arrow,
+.vp-abbr-popover .tooltip-arrow::after {
+  position: absolute;
+  display: block;
+  width: 8px;
+  height: 8px;
+  border: 8px solid transparent;
+}
+
+.vp-abbr-popover .tooltip-arrow {
+  top: -16px;
+  left: 4px;
+  border-bottom-color: var(--vp-c-divider);
+}
+
+.vp-abbr-popover .tooltip-arrow::after {
+  content: "";
+  border-bottom-color: var(--vp-c-bg);
+  transform: translate(-8px, -7px);
+}

package/dist/node/index.d.ts

@@ -0,0 +1,82 @@
+import { PluginWithOptions } from "markdown-it";
+
+//#region src/node/plugin.d.ts
+/**
+ * VitePress plugin for abbreviation support in markdown content.
+ *
+ * VitePress 插件，用于在 markdown 内容中支持缩写词。
+ *
+ * Forked and modified from `markdown-it-abbr`. The plugin registers the
+ * abbreviation definition and replace rules in markdown-it, and wires up the
+ * client-side `VPAbbreviation` component via `componentResolver` so that
+ * abbreviations render with an interactive tooltip showing their full
+ * description. It also pre-bundles the `@floating-ui/vue` dependency used by
+ * the tooltip.
+ *
+ * 从 `markdown-it-abbr` 分叉并修改。该插件在 markdown-it 中注册缩写词
+ * 定义与替换规则，并通过 `componentResolver` 接入客户端 `VPAbbreviation`
+ * 组件，使缩写词渲染时带有可交互的提示框，展示其完整描述。同时预构建
+ * 提示框所依赖的 `@floating-ui/vue`。
+ *
+ * Abbreviations can be defined inline in markdown using the syntax
+ * `*[ABBR]: Full description`, or provided globally through the
+ * `abbreviations` option. Inline definitions take precedence over global ones
+ * when both define the same abbreviation.
+ *
+ * 缩写词可以在 markdown 中通过 `*[缩写]: 完整描述` 语法内联定义，也可以
+ * 通过 `abbreviations` 选项全局提供。当两者定义了相同的缩写词时，内联
+ * 定义优先于全局定义。
+ *
+ * @param abbreviations - Global abbreviations preset, a map of abbreviation
+ *   to its full description / 全局缩写词预设，缩写词到其完整描述的映射
+ * @example
+ * `.vitepress/config.ts` without global abbreviations
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import abbr from 'vitepress-plugin-abbr'
+ *
+ * export default defineConfig({
+ *   plugins: [abbr()],
+ * })
+ * ```
+ * @example
+ * `.vitepress/config.ts` with global abbreviations
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import abbr from 'vitepress-plugin-abbr'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     abbr({
+ *       HTML: 'HyperText Markup Language',
+ *       W3C: 'World Wide Web Consortium',
+ *     }),
+ *   ],
+ * })
+ * ```
+ * @example
+ * // Markdown usage
+ * ```md
+ * The HTML specification is maintained by the W3C.
+ *
+ * *[HTML]: HyperText Markup Language
+ * *[W3C]: World Wide Web Consortium
+ * ```
+ */
+declare const abbr: (options?: Record<string, string> | undefined) => import("vitepress-tuck").VitepressPlugin;
+//#endregion
+//#region src/node/markdown.d.ts
+/**
+ * Abbreviation plugin - Enable abbreviation syntax
+ *
+ * 缩写词插件 - 启用缩写词语法
+ *
+ * Definition syntax: *[ABBREV]: Full description
+ * 定义语法：*[缩写]: 完整描述
+ *
+ * @param md - Markdown-it instance / Markdown-it 实例
+ * @param globalAbbreviations - Global abbreviations preset / 全局缩写词预设
+ */
+declare const abbrMarkdownPlugin: PluginWithOptions<Record<string, string>>;
+//#endregion
+export { abbr, abbr as default, abbrMarkdownPlugin };

package/dist/node/index.js

@@ -0,0 +1,282 @@
+import { definePlugin } from "vitepress-tuck";
+import { cleanMarkdownEnv } from "vitepress-plugin-toolkit";
+//#region ../../node_modules/.pnpm/@pengzhanbo+utils@3.7.3/node_modules/@pengzhanbo/utils/dist/index.js
+const T_NULL = "null";
+const DANGEROUS_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function getTypeName(s) {
+	return Object.prototype.toString.call(s);
+}
+function typeOf(s) {
+	const type = typeof s;
+	return s === null ? T_NULL : type === "object" || type === "function" ? getTypeName(s).slice(8, -1).toLowerCase() : type;
+}
+function isTypeof(s, type) {
+	return typeOf(s) === type;
+}
+function isNull(v) {
+	return v === null;
+}
+function isPlainObject(v) {
+	if (!isTypeof(v, "object")) return false;
+	const proto = Object.getPrototypeOf(v);
+	return isNull(proto) || proto === Object.prototype;
+}
+function isEmptyObject(v) {
+	if (!isPlainObject(v)) return false;
+	for (const _ in v) return false;
+	return true;
+}
+function objectKeys(obj) {
+	return Object.keys(obj);
+}
+function objectMap(obj, mapper) {
+	return Object.fromEntries(Object.entries(obj).map(([k, v]) => mapper(k, v)).filter((entry) => !isUndefined(entry)).filter(([k]) => !DANGEROUS_KEYS.has(k)));
+}
+function isUndefined(v) {
+	return v === void 0;
+}
+//#endregion
+//#region src/node/markdown.ts
+/**
+* Abbreviation plugin - Enable abbreviation syntax
+*
+* 缩写词插件 - 启用缩写词语法
+*
+* Definition syntax: *[ABBREV]: Full description
+* 定义语法：*[缩写]: 完整描述
+*
+* @param md - Markdown-it instance / Markdown-it 实例
+* @param globalAbbreviations - Global abbreviations preset / 全局缩写词预设
+*/
+const abbrMarkdownPlugin = (md, globalAbbreviations = {}) => {
+	const { arrayReplaceAt, escapeRE, lib } = md.utils;
+	globalAbbreviations = objectMap(globalAbbreviations, (key, value) => [key.startsWith(":") ? key : `:${key}`, value]);
+	const WORDING_REGEXP_TEXT = `${lib.ucmicro.P.source}|${lib.ucmicro.Z.source}|[${" \r\n$+<=>^`|~".split("").map(escapeRE).join("")}]`;
+	/**
+	* Abbreviation definition rule
+	*
+	* 缩写词定义规则
+	*
+	* @param state - State block / 状态块
+	* @param startLine - Start line number / 开始行号
+	* @param _endLine - End line number / 结束行号
+	* @param silent - Silent mode / 静默模式
+	* @returns Whether matched / 是否匹配
+	*/
+	const abbrDefinition = (state, startLine, _endLine, silent) => {
+		let labelEnd = -1;
+		let pos = state.bMarks[startLine] + state.tShift[startLine];
+		const max = state.eMarks[startLine];
+		if (pos + 2 >= max || state.src.charAt(pos++) !== "*" || state.src.charAt(pos++) !== "[") return false;
+		const labelStart = pos;
+		while (pos < max) {
+			const ch = state.src.charAt(pos);
+			if (ch === "[") return false;
+			if (ch === "]") {
+				labelEnd = pos;
+				break;
+			}
+			if (ch === "\\") pos++;
+			pos++;
+		}
+		if (labelEnd < 0 || state.src.charAt(labelEnd + 1) !== ":") return false;
+		/* istanbul ignore if -- @preserve */
+		if (silent) return true;
+		const label = state.src.slice(labelStart, labelEnd).replace(/\\(.)/g, "$1");
+		const title = state.src.slice(labelEnd + 2, max).trim();
+		if (!label.length || !title.length) return false;
+		(state.env.abbreviations ??= {})[`:${label}`] ??= title;
+		state.line = startLine + 1;
+		return true;
+	};
+	/**
+	* Abbreviation replace rule
+	*
+	* 缩写词替换规则
+	*
+	* @param state - State core / 核心状态
+	*/
+	const abbrReplace = (state) => {
+		if (state.env.disableAbbrReplace) return;
+		const tokens = state.tokens;
+		const { abbreviations: localAbbreviations } = state.env;
+		if (!localAbbreviations && isEmptyObject(globalAbbreviations)) return;
+		const abbreviations = {
+			...globalAbbreviations,
+			...localAbbreviations
+		};
+		const abbreviationsRegExpText = objectKeys(abbreviations).map((x) => x.substring(1)).sort((a, b) => b.length - a.length).map(escapeRE).join("|");
+		const regexpSimple = new RegExp(`(?:${abbreviationsRegExpText})`);
+		const regExp = new RegExp(`(^|${WORDING_REGEXP_TEXT})(${abbreviationsRegExpText})($|${WORDING_REGEXP_TEXT})`, "g");
+		for (const token of tokens) {
+			if (token.type !== "inline") continue;
+			let children = token.children;
+			for (let index = children.length - 1; index >= 0; index--) {
+				const currentToken = children[index];
+				if (currentToken.type !== "text") continue;
+				const text = currentToken.content;
+				regExp.lastIndex = 0;
+				if (!regexpSimple.test(text)) continue;
+				const nodes = [];
+				let match;
+				let pos = 0;
+				while (match = regExp.exec(text)) {
+					const [, before, word, after] = match;
+					if (match.index > 0 || before.length > 0) {
+						const token = new state.Token("text", "", 0);
+						token.content = text.slice(pos, match.index + before.length);
+						nodes.push(token);
+					}
+					const abbrToken = new state.Token("abbreviation", "Abbreviation", 0);
+					abbrToken.content = word;
+					abbrToken.info = abbreviations[`:${word}`];
+					nodes.push(abbrToken);
+					regExp.lastIndex -= after.length;
+					pos = regExp.lastIndex;
+				}
+				/* istanbul ignore if -- @preserve */
+				if (!nodes.length) continue;
+				if (pos < text.length) {
+					const token = new state.Token("text", "", 0);
+					token.content = text.slice(pos);
+					nodes.push(token);
+				}
+				token.children = children = arrayReplaceAt(children, index, nodes);
+			}
+		}
+	};
+	md.block.ruler.before("reference", "abbr_definition", abbrDefinition, { alt: ["paragraph", "reference"] });
+	md.core.ruler.after("linkify", "abbr_replace", abbrReplace);
+	/**
+	* Custom renderer for the `abbreviation` token.
+	*
+	* `abbreviation` token 的自定义渲染器。
+	*
+	* Renders the abbreviation as a `VPAbbreviation` component tag. The
+	* abbreviation text is placed as the default slot content, and when a
+	* description (`info`) exists, it is rendered as inline markdown and passed
+	* to the `#tooltip` slot. The rendered description is also used to produce
+	* an `aria-label` (HTML tags stripped) for accessibility.
+	*
+	* 将缩写词渲染为 `VPAbbreviation` 组件标签。缩写词文本作为默认插槽内容，
+	* 当存在描述（`info`）时，将其作为内联 markdown 渲染后传入 `#tooltip`
+	* 插槽。渲染后的描述还会去除 HTML 标签生成 `aria-label`，以支持无障碍访问。
+	*
+	* @param tokens - Token array / token 数组
+	* @param idx - Current token index / 当前 token 索引
+	* @param _ - Render options (unused) / 渲染选项（未使用）
+	* @param env - Render environment containing abbreviations / 包含缩写词的渲染环境
+	* @returns Rendered HTML string / 渲染后的 HTML 字符串
+	*/
+	md.renderer.rules.abbreviation = (tokens, idx, _, env) => {
+		const { content, info } = tokens[idx];
+		const rendered = md.renderInline(info, {
+			...cleanMarkdownEnv(env, ["abbreviations"]),
+			disableAbbrReplace: true
+		});
+		return `<VPAbbreviation aria-label="${rendered.replace(/<[^>]*>/g, "")}">${content}${info ? `<template #tooltip>${rendered}</template>` : ""}</VPAbbreviation>`;
+	};
+};
+//#endregion
+//#region src/node/plugin.ts
+/**
+* VitePress plugin for abbreviation support in markdown content.
+*
+* VitePress 插件，用于在 markdown 内容中支持缩写词。
+*
+* Forked and modified from `markdown-it-abbr`. The plugin registers the
+* abbreviation definition and replace rules in markdown-it, and wires up the
+* client-side `VPAbbreviation` component via `componentResolver` so that
+* abbreviations render with an interactive tooltip showing their full
+* description. It also pre-bundles the `@floating-ui/vue` dependency used by
+* the tooltip.
+*
+* 从 `markdown-it-abbr` 分叉并修改。该插件在 markdown-it 中注册缩写词
+* 定义与替换规则，并通过 `componentResolver` 接入客户端 `VPAbbreviation`
+* 组件，使缩写词渲染时带有可交互的提示框，展示其完整描述。同时预构建
+* 提示框所依赖的 `@floating-ui/vue`。
+*
+* Abbreviations can be defined inline in markdown using the syntax
+* `*[ABBR]: Full description`, or provided globally through the
+* `abbreviations` option. Inline definitions take precedence over global ones
+* when both define the same abbreviation.
+*
+* 缩写词可以在 markdown 中通过 `*[缩写]: 完整描述` 语法内联定义，也可以
+* 通过 `abbreviations` 选项全局提供。当两者定义了相同的缩写词时，内联
+* 定义优先于全局定义。
+*
+* @param abbreviations - Global abbreviations preset, a map of abbreviation
+*   to its full description / 全局缩写词预设，缩写词到其完整描述的映射
+* @example
+* `.vitepress/config.ts` without global abbreviations
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import abbr from 'vitepress-plugin-abbr'
+*
+* export default defineConfig({
+*   plugins: [abbr()],
+* })
+* ```
+* @example
+* `.vitepress/config.ts` with global abbreviations
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import abbr from 'vitepress-plugin-abbr'
+*
+* export default defineConfig({
+*   plugins: [
+*     abbr({
+*       HTML: 'HyperText Markup Language',
+*       W3C: 'World Wide Web Consortium',
+*     }),
+*   ],
+* })
+* ```
+* @example
+* // Markdown usage
+* ```md
+* The HTML specification is maintained by the W3C.
+*
+* *[HTML]: HyperText Markup Language
+* *[W3C]: World Wide Web Consortium
+* ```
+*/
+const abbr = definePlugin((abbreviations) => ({
+	name: "vitepress-plugin-abbr",
+	componentResolver: ["VPAbbreviation"],
+	markdown: { config(md) {
+		md.use(abbrMarkdownPlugin, abbreviations);
+	} },
+	vite: { optimizeDeps: { include: ["@floating-ui/vue"] } }
+}));
+//#endregion
+//#region src/node/index.ts
+/**
+* Node-side entry point for the VitePress abbreviation plugin.
+*
+* VitePress 缩写词插件的 Node 端入口。
+*
+* Re-exports the markdown-it plugin and the main plugin factory, and exposes
+* the plugin factory as the default export for `vitepress-tuck` integration.
+*
+* 重新导出 markdown-it 插件和主插件工厂，并将插件工厂作为默认导出，
+* 以便与 `vitepress-tuck` 集成。
+*
+* @example
+* `.vitepress/config.ts`
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import abbr from 'vitepress-plugin-abbr'
+*
+* export default defineConfig({
+*   plugins: [abbr()],
+* })
+* ```
+*/
+var node_default = abbr;
+//#endregion
+export { abbr, abbrMarkdownPlugin, node_default as default };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "vitepress-plugin-abbr",
+  "type": "module",
+  "version": "0.5.0",
+  "description": "Add abbreviation support to VitePress",
+  "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
+  "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/plugins/abbr",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
+    "directory": "packages/plugin-abbr"
+  },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
+  "keywords": [
+    "vitepress",
+    "vitepress-plugin",
+    "abbr",
+    "abbreviation"
+  ],
+  "exports": {
+    ".": "./dist/node/index.js",
+    "./client": {
+      "browser": "./dist/client/browser/index.js",
+      "default": "./dist/client/ssr/index.js"
+    },
+    "./style.css": "./dist/client/style.css"
+  },
+  "module": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "vitepress": "^1.6.4 || ^2.0.0-alpha.17",
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "@floating-ui/vue": "^2.0.0",
+    "@vueuse/core": "^14.3.0",
+    "vitepress-plugin-toolkit": "0.5.0",
+    "vitepress-tuck": "0.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rimraf --glob ./dist",
+    "dev": "pnpm '/(tsdown|copy):watch/'",
+    "build": "pnpm tsdown && pnpm copy",
+    "copy": "cpx \"src/**/*.css\" dist",
+    "copy:watch": "pnpm copy -w",
+    "tsdown": "tsdown --config-loader unrun",
+    "tsdown:watch": "pnpm tsdown -w"
+  }
+}