vitepress-plugin-annotation 0.7.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,199 @@
+# vitepress-plugin-annotation
+
+Add annotation support to your VitePress site, rendering annotation references as interactive
+markers that reveal a popover with the annotation content on click.
+
+为 VitePress 添加注释支持，将注释引用渲染为可交互的标记，点击后弹出包含注释内容的浮层。
+
+## Usage
+
+### With Vitepress-tuck
+
+**Installation:**
+
+```bash
+# npm
+npm install -D vitepress-tuck vitepress-plugin-annotation
+# pnpm
+pnpm add -D vitepress-tuck vitepress-plugin-annotation
+# yarn
+yarn add -D vitepress-tuck vitepress-plugin-annotation
+```
+
+**Configuration:**
+
+```ts
+// .vitepress/config.ts
+import annotation from 'vitepress-plugin-annotation'
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  plugins: [annotation()],
+})
+```
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import enhanceApp from 'virtual:enhance-app'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceApp(ctx)
+  },
+} satisfies Theme
+```
+
+### With Vitepress
+
+**Installation:**
+
+```bash
+# npm
+npm install -D vitepress-plugin-annotation
+# pnpm
+pnpm add -D vitepress-plugin-annotation
+# yarn
+yarn add -D vitepress-plugin-annotation
+```
+
+**Configuration:**
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress'
+import { annotationMarkdownPlugin } from 'vitepress-plugin-annotation'
+
+export default defineConfig({
+  markdown: {
+    config: (md) => {
+      md.use(annotationMarkdownPlugin)
+    },
+  },
+})
+```
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import { enhanceAppWithAnnotation } from 'vitepress-plugin-annotation/client'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceAppWithAnnotation(ctx)
+  },
+} satisfies Theme
+```
+
+## Syntax
+
+Define an annotation with the `[+label]: annotation content` syntax, then reference it anywhere
+in your markdown content using `[+label]`. The reference is rendered as a small interactive
+marker that, on click, reveals a popover displaying the annotation content.
+
+使用 `[+标签]: 注释内容` 语法定义注释，然后在 markdown 内容的任意位置使用 `[+标签]`
+进行引用。引用会渲染为一个小的可交互标记，点击后弹出显示注释内容的浮层。
+
+```md
+The **four great classical novels** [+novels] of Chinese literature are widely known.
+
+[+novels]:
+  **Romance of the Three Kingdoms** — a historical novel set in the Three Kingdoms period.
+
+[+novels]:
+  **Journey to the West** — a mythological tale of a pilgrimage to the West.
+```
+
+The annotation content supports full block-level markdown, including headings, paragraphs,
+lists, code blocks, and more.
+
+注释内容支持完整的块级 markdown 语法，包括标题、段落、列表、代码块等。
+
+```md
+The framework is built on [+vue].
+
+[+vue]:
+  ## Vue
+
+  A progressive framework for building user interfaces.
+
+  - Reactive data binding
+  - Component-based architecture
+  - [Learn more](https://vuejs.org/)
+```
+
+### Multi-line Definitions
+
+Annotation definitions can span multiple lines. Continuation lines must be indented by at
+least two spaces relative to the definition. Empty lines within the indented block are
+preserved as part of the annotation content. A non-indented content line (such as the next
+definition or a new paragraph) terminates the multi-line definition.
+
+注释定义可以跨多行。续行必须相对于定义至少缩进两个空格。缩进块内的空行会作为
+注释内容的一部分被保留。非缩进的内容行（如下一个定义或新段落）会终止多行定义。
+
+```md
+This concept is explained in [+detail].
+
+[+detail]:
+  This is the first paragraph of the annotation.
+
+  This is the second paragraph, separated by an empty line
+  but still part of the same annotation.
+
+The annotation definition ends here because this line is not indented.
+```
+
+### Multiple Definitions per Label
+
+A single label can be defined multiple times. All definitions are collected and displayed
+as separate items in the popover, allowing you to provide multiple pieces of related
+information for the same reference.
+
+同一标签可以多次定义。所有定义会被收集并作为独立条目展示在浮层中，允许你为同一
+引用提供多条相关信息。
+
+```md
+JavaScript has multiple [+js] versions.
+
+[+js]:
+  **ES2015 (ES6)** — Introduced classes, modules, arrows, and more.
+
+[+js]:
+  **ES2020** — Added optional chaining, nullish coalescing, and BigInt.
+```
+
+## Global Annotations
+
+Instead of (or in addition to) defining annotations inline in each markdown file, you can
+provide a global preset of annotations through the plugin options. This is useful for terms
+that should be annotated consistently across all pages.
+
+可以在每个 markdown 文件中内联定义注释，也可以通过插件选项提供全局注释预设。
+这对于需要在所有页面中一致注释的术语很有用。
+
+```ts
+// .vitepress/config.ts
+import annotation from 'vitepress-plugin-annotation'
+import { defineConfig } from 'vitepress-tuck'
+
+export default defineConfig({
+  plugins: [
+    annotation({
+      HTML: 'HyperText Markup Language',
+      CSS: ['Cascading Style Sheets', 'A style sheet language used for describing the presentation of a document.'],
+    }),
+  ],
+})
+```
+
+Each global annotation value can be a string or an array of strings. When an array is
+provided, each element becomes a separate item in the popover, just like multiple inline
+definitions for the same label.
+
+每个全局注释值可以是字符串或字符串数组。当提供数组时，每个元素成为浮层中的
+一个独立条目，就像同一标签的多个内联定义一样。

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

@@ -0,0 +1,47 @@
+import { EnhanceAppContext } from "vitepress";
+
+//#region src/client/VPAnnotation.vue.d.ts
+type __VLS_Props = {
+  label: string;
+  total: number;
+};
+declare var __VLS_20: `item-${number}`, __VLS_21: {};
+type __VLS_Slots = {} & { [K in NonNullable<typeof __VLS_20>]?: (props: typeof __VLS_21) => any };
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, 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 `VPAnnotation`
+ * component globally under the name `VPAnnotation`, so it can be used
+ * directly in Vue templates or rendered markdown content.
+ *
+ * 通过全局注册 `VPAnnotation` 组件来增强 VitePress 应用，
+ * 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+ *
+ * @example
+ * `.vitepress/theme/index.ts`
+ * ```ts
+ * import type { Theme } from 'vitepress'
+ * import { enhanceAppWithAnnotation } from 'vitepress-plugin-annotation/client'
+ * import DefaultTheme from 'vitepress/theme'
+ *
+ * export default {
+ *   extends: DefaultTheme,
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithAnnotation(ctx)
+ *   },
+ * } satisfies Theme
+ * ```
+ */
+declare function enhanceAppWithAnnotation({
+  app
+}: EnhanceAppContext): void;
+//#endregion
+export { _default as VPAnnotation, enhanceAppWithAnnotation };

package/dist/client/browser/index.js

@@ -0,0 +1,126 @@
+import "../style.css";
+import { Fragment, Teleport, Transition, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, mergeProps, normalizeClass, normalizeStyle, openBlock, ref, renderList, renderSlot, resolveComponent, unref, useTemplateRef, withCtx } from "vue";
+import { autoUpdate, flip, shift, useFloating } from "@floating-ui/vue";
+import { onClickOutside, useIntersectionObserver } from "@vueuse/core";
+//#region src/client/VPAnnotation.vue
+const _hoisted_1 = ["aria-label", "aria-expanded"];
+const _sfc_main = /*@__PURE__*/ defineComponent({
+	inheritAttrs: false,
+	__name: "VPAnnotation",
+	props: {
+		label: {},
+		total: {}
+	},
+	setup(__props) {
+		/**
+		* VPAnnotation component for rendering annotation references with an
+		* interactive popover in VitePress.
+		*
+		* VPAnnotation 组件，用于在 VitePress 中渲染带有可交互浮层的注释引用。
+		*
+		* The annotation marker is rendered as a small inline span (styled via CSS as
+		* a superscript-like icon). When the user clicks or focuses the marker, a
+		* floating popover anchored to the marker is shown, displaying the annotation
+		* content provided via the `#item-0`, `#item-1`, … named slots. Each slot
+		* corresponds to one definition of the annotation label. The popover is
+		* teleported to `body` and positioned with `@floating-ui/vue`, applying
+		* offset, flip, and shift middleware for robust placement near viewport edges.
+		*
+		* 注释标记渲染为一个小型行内 span（通过 CSS 样式为类上标图标）。当用户点击或
+		* 聚焦该标记时，会显示一个锚定到标记的浮动浮层，展示通过 `#item-0`、
+		* `#item-1`、… 具名插槽提供的注释内容。每个插槽对应注释标签的一个定义。
+		* 浮层被传送到 `body`，并使用 `@floating-ui/vue` 定位，应用 offset、flip 和
+		* shift 中间件以保证在视口边缘附近的稳定定位。
+		*
+		* The popover automatically closes when:
+		* - The user clicks outside the marker and popover.
+		* - The marker scrolls out of the viewport.
+		*
+		* 浮层在以下情况下自动关闭：
+		* - 用户点击标记和浮层之外的区域。
+		* - 标记滚动出视口。
+		*/
+		const active = ref(false);
+		const group = computed(() => Array.from({ length: __props.total }, (_, i) => i));
+		const annotation = useTemplateRef("annotation");
+		const tooltip = useTemplateRef("tooltip");
+		onClickOutside(annotation, () => {
+			active.value = false;
+		}, { ignore: [tooltip] });
+		useIntersectionObserver(annotation, ([entry]) => {
+			if (!entry.isIntersecting && active.value) active.value = false;
+		}, { rootMargin: "-64px 0px 0px 0px" });
+		const { floatingStyles, placement } = useFloating(annotation, tooltip, {
+			whileElementsMounted: autoUpdate,
+			middleware: [flip(), shift({ padding: {
+				top: 80,
+				left: 16,
+				bottom: 16
+			} })]
+		});
+		const inset = computed(() => placement.value.split("-")[0]);
+		return (_ctx, _cache) => {
+			const _component_ClientOnly = resolveComponent("ClientOnly");
+			return openBlock(), createElementBlock(Fragment, null, [createElementVNode("button", mergeProps(_ctx.$attrs, {
+				ref_key: "annotation",
+				ref: annotation,
+				type: "button",
+				class: ["vp-annotation", {
+					[__props.label]: true,
+					[inset.value]: true,
+					active: active.value
+				}],
+				"aria-label": __props.label,
+				"aria-expanded": active.value,
+				onClick: _cache[0] || (_cache[0] = ($event) => active.value = !active.value)
+			}), [..._cache[1] || (_cache[1] = [createElementVNode("span", { class: "vpi-annotation" }, null, -1)])], 16, _hoisted_1), createVNode(_component_ClientOnly, null, {
+				default: withCtx(() => [(openBlock(), createBlock(Teleport, { to: "body" }, [createVNode(Transition, { name: "fade-in" }, {
+					default: withCtx(() => [active.value ? (openBlock(), createElementBlock("div", {
+						key: 0,
+						ref_key: "tooltip",
+						ref: tooltip,
+						class: normalizeClass(["vp-annotation-popover", { group: group.value.length > 1 }]),
+						style: normalizeStyle(unref(floatingStyles))
+					}, [(openBlock(true), createElementBlock(Fragment, null, renderList(group.value, (i) => {
+						return openBlock(), createElementBlock("div", {
+							key: __props.label + i,
+							class: "annotation"
+						}, [renderSlot(_ctx.$slots, `item-${i}`)]);
+					}), 128))], 6)) : createCommentVNode("v-if", true)]),
+					_: 3
+				})]))]),
+				_: 3
+			})], 64);
+		};
+	}
+});
+//#endregion
+//#region src/client/index.ts
+/**
+* Enhances the VitePress application by registering the `VPAnnotation`
+* component globally under the name `VPAnnotation`, so it can be used
+* directly in Vue templates or rendered markdown content.
+*
+* 通过全局注册 `VPAnnotation` 组件来增强 VitePress 应用，
+* 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+*
+* @example
+* `.vitepress/theme/index.ts`
+* ```ts
+* import type { Theme } from 'vitepress'
+* import { enhanceAppWithAnnotation } from 'vitepress-plugin-annotation/client'
+* import DefaultTheme from 'vitepress/theme'
+*
+* export default {
+*   extends: DefaultTheme,
+*   enhanceApp(ctx) {
+*     enhanceAppWithAnnotation(ctx)
+*   },
+* } satisfies Theme
+* ```
+*/
+function enhanceAppWithAnnotation({ app }) {
+	app.component("VPAnnotation", _sfc_main);
+}
+//#endregion
+export { _sfc_main as VPAnnotation, enhanceAppWithAnnotation };

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

@@ -0,0 +1,47 @@
+import { EnhanceAppContext } from "vitepress";
+
+//#region src/client/VPAnnotation.vue.d.ts
+type __VLS_Props = {
+  label: string;
+  total: number;
+};
+declare var __VLS_20: `item-${number}`, __VLS_21: {};
+type __VLS_Slots = {} & { [K in NonNullable<typeof __VLS_20>]?: (props: typeof __VLS_21) => any };
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, 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 `VPAnnotation`
+ * component globally under the name `VPAnnotation`, so it can be used
+ * directly in Vue templates or rendered markdown content.
+ *
+ * 通过全局注册 `VPAnnotation` 组件来增强 VitePress 应用，
+ * 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+ *
+ * @example
+ * `.vitepress/theme/index.ts`
+ * ```ts
+ * import type { Theme } from 'vitepress'
+ * import { enhanceAppWithAnnotation } from 'vitepress-plugin-annotation/client'
+ * import DefaultTheme from 'vitepress/theme'
+ *
+ * export default {
+ *   extends: DefaultTheme,
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithAnnotation(ctx)
+ *   },
+ * } satisfies Theme
+ * ```
+ */
+declare function enhanceAppWithAnnotation({
+  app
+}: EnhanceAppContext): void;
+//#endregion
+export { _default as VPAnnotation, enhanceAppWithAnnotation };

package/dist/client/ssr/index.js

@@ -0,0 +1,146 @@
+import { Fragment, Teleport, Transition, computed, createBlock, createCommentVNode, createVNode, defineComponent, mergeProps, openBlock, ref, renderList, renderSlot, resolveComponent, unref, useSSRContext, useTemplateRef, withCtx } from "vue";
+import { ssrRenderAttrs, ssrRenderClass, ssrRenderComponent, ssrRenderList, ssrRenderSlot, ssrRenderStyle, ssrRenderTeleport } from "vue/server-renderer";
+import { autoUpdate, flip, shift, useFloating } from "@floating-ui/vue";
+import { onClickOutside, useIntersectionObserver } from "@vueuse/core";
+//#region src/client/VPAnnotation.vue
+const _sfc_main = /*@__PURE__*/ defineComponent({
+	inheritAttrs: false,
+	__name: "VPAnnotation",
+	__ssrInlineRender: true,
+	props: {
+		label: {},
+		total: {}
+	},
+	setup(__props) {
+		/**
+		* VPAnnotation component for rendering annotation references with an
+		* interactive popover in VitePress.
+		*
+		* VPAnnotation 组件，用于在 VitePress 中渲染带有可交互浮层的注释引用。
+		*
+		* The annotation marker is rendered as a small inline span (styled via CSS as
+		* a superscript-like icon). When the user clicks or focuses the marker, a
+		* floating popover anchored to the marker is shown, displaying the annotation
+		* content provided via the `#item-0`, `#item-1`, … named slots. Each slot
+		* corresponds to one definition of the annotation label. The popover is
+		* teleported to `body` and positioned with `@floating-ui/vue`, applying
+		* offset, flip, and shift middleware for robust placement near viewport edges.
+		*
+		* 注释标记渲染为一个小型行内 span（通过 CSS 样式为类上标图标）。当用户点击或
+		* 聚焦该标记时，会显示一个锚定到标记的浮动浮层，展示通过 `#item-0`、
+		* `#item-1`、… 具名插槽提供的注释内容。每个插槽对应注释标签的一个定义。
+		* 浮层被传送到 `body`，并使用 `@floating-ui/vue` 定位，应用 offset、flip 和
+		* shift 中间件以保证在视口边缘附近的稳定定位。
+		*
+		* The popover automatically closes when:
+		* - The user clicks outside the marker and popover.
+		* - The marker scrolls out of the viewport.
+		*
+		* 浮层在以下情况下自动关闭：
+		* - 用户点击标记和浮层之外的区域。
+		* - 标记滚动出视口。
+		*/
+		const active = ref(false);
+		const group = computed(() => Array.from({ length: __props.total }, (_, i) => i));
+		const annotation = useTemplateRef("annotation");
+		const tooltip = useTemplateRef("tooltip");
+		onClickOutside(annotation, () => {
+			active.value = false;
+		}, { ignore: [tooltip] });
+		useIntersectionObserver(annotation, ([entry]) => {
+			if (!entry.isIntersecting && active.value) active.value = false;
+		}, { rootMargin: "-64px 0px 0px 0px" });
+		const { floatingStyles, placement } = useFloating(annotation, tooltip, {
+			whileElementsMounted: autoUpdate,
+			middleware: [flip(), shift({ padding: {
+				top: 80,
+				left: 16,
+				bottom: 16
+			} })]
+		});
+		const inset = computed(() => placement.value.split("-")[0]);
+		return (_ctx, _push, _parent, _attrs) => {
+			const _component_ClientOnly = resolveComponent("ClientOnly");
+			_push(`<!--[--><button${ssrRenderAttrs(mergeProps(_ctx.$attrs, {
+				ref_key: "annotation",
+				ref: annotation,
+				type: "button",
+				class: ["vp-annotation", {
+					[__props.label]: true,
+					[inset.value]: true,
+					active: active.value
+				}],
+				"aria-label": __props.label,
+				"aria-expanded": active.value
+			}))}><span class="vpi-annotation"></span></button>`);
+			_push(ssrRenderComponent(_component_ClientOnly, null, {
+				default: withCtx((_, _push, _parent, _scopeId) => {
+					if (_push) ssrRenderTeleport(_push, (_push) => {
+						if (active.value) {
+							_push(`<div class="${ssrRenderClass([{ group: group.value.length > 1 }, "vp-annotation-popover"])}" style="${ssrRenderStyle(unref(floatingStyles))}"${_scopeId}><!--[-->`);
+							ssrRenderList(group.value, (i) => {
+								_push(`<div class="annotation"${_scopeId}>`);
+								ssrRenderSlot(_ctx.$slots, `item-${i}`, {}, null, _push, _parent, _scopeId);
+								_push(`</div>`);
+							});
+							_push(`<!--]--></div>`);
+						} else _push(`<!---->`);
+					}, "body", false, _parent);
+					else return [(openBlock(), createBlock(Teleport, { to: "body" }, [createVNode(Transition, { name: "fade-in" }, {
+						default: withCtx(() => [active.value ? (openBlock(), createBlock("div", {
+							key: 0,
+							ref_key: "tooltip",
+							ref: tooltip,
+							class: ["vp-annotation-popover", { group: group.value.length > 1 }],
+							style: unref(floatingStyles)
+						}, [(openBlock(true), createBlock(Fragment, null, renderList(group.value, (i) => {
+							return openBlock(), createBlock("div", {
+								key: __props.label + i,
+								class: "annotation"
+							}, [renderSlot(_ctx.$slots, `item-${i}`)]);
+						}), 128))], 6)) : createCommentVNode("v-if", true)]),
+						_: 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/VPAnnotation.vue");
+	return _sfc_setup ? _sfc_setup(props, ctx) : void 0;
+};
+//#endregion
+//#region src/client/index.ts
+/**
+* Enhances the VitePress application by registering the `VPAnnotation`
+* component globally under the name `VPAnnotation`, so it can be used
+* directly in Vue templates or rendered markdown content.
+*
+* 通过全局注册 `VPAnnotation` 组件来增强 VitePress 应用，
+* 使其可在 Vue 模板或渲染的 markdown 内容中直接使用。
+*
+* @example
+* `.vitepress/theme/index.ts`
+* ```ts
+* import type { Theme } from 'vitepress'
+* import { enhanceAppWithAnnotation } from 'vitepress-plugin-annotation/client'
+* import DefaultTheme from 'vitepress/theme'
+*
+* export default {
+*   extends: DefaultTheme,
+*   enhanceApp(ctx) {
+*     enhanceAppWithAnnotation(ctx)
+*   },
+* } satisfies Theme
+* ```
+*/
+function enhanceAppWithAnnotation({ app }) {
+	app.component("VPAnnotation", _sfc_main);
+}
+//#endregion
+export { _sfc_main as VPAnnotation, enhanceAppWithAnnotation };

package/dist/client/style.css

@@ -0,0 +1,110 @@
+@import url("vitepress-plugin-toolkit/styles/transition/fade-in.css");
+
+.vp-annotation {
+  position: relative;
+  top: -2px;
+  z-index: 10;
+  display: inline-block;
+  width: 1.5em;
+  height: 1.5em;
+  color: currentcolor;
+  vertical-align: middle;
+  cursor: pointer;
+  user-select: none;
+  opacity: 0.5;
+  transition: 0.25s ease-in-out;
+  transition-property: color, opacity, transform;
+  transform: rotate(0deg);
+}
+
+@media print {
+  .vp-annotation {
+    display: none;
+  }
+}
+
+.vp-annotation:where(:hover, .active) {
+  color: var(--vp-c-brand-2) !important;
+  opacity: 1;
+}
+
+.vp-annotation.active.top {
+  transform: rotate(135deg);
+}
+
+.vp-annotation.active.left {
+  transform: rotate(45deg);
+}
+
+.vp-annotation.active.bottom {
+  transform: rotate(-45deg);
+}
+
+.vp-annotation.active.right {
+  transform: rotate(-135deg);
+}
+
+.vp-annotation .vpi-annotation {
+  --icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24'%3E%3Cpath fill='%23000' fill-rule='evenodd' d='M2 12C2 6.477 6.477 2 12 2s10 4.477 10 10s-4.477 10-10 10a10 10 0 0 1-4.262-.951l-4.537.93a1 1 0 0 1-1.18-1.18l.93-4.537A10 10 0 0 1 2 12m10-4a1 1 0 0 1 1 1v2h2a1 1 0 1 1 0 2h-2v2a1 1 0 1 1-2 0v-2H9a1 1 0 1 1 0-2h2V9a1 1 0 0 1 1-1' clip-rule='evenodd'/%3E%3C/svg%3E");
+
+  display: inline-block;
+  width: 100%;
+  height: 100%;
+}
+
+.vp-annotation-popover {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 1;
+  width: max-content;
+  max-width: min(calc(100vw - 32px), 360px);
+  max-height: 360px;
+  padding-block: 8px;
+  padding-inline: 12px;
+  overflow: auto;
+  font-size: 14px;
+  font-weight: normal;
+  background-color: var(--vp-c-bg);
+  border: solid 1px var(--vp-c-divider);
+  border-radius: 8px;
+  box-shadow: var(--vp-shadow-2);
+}
+
+.vp-annotation-popover.group {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 12px;
+  background-color: var(--vp-c-bg-soft);
+}
+
+.vp-annotation-popover.group .annotation {
+  padding-block: 4px;
+  padding-inline: 12px;
+  background-color: var(--vp-c-bg);
+  border-radius: 4px;
+  box-shadow: var(--vp-shadow-1);
+}
+
+.vp-annotation-popover p {
+  margin-block: 12px;
+  margin-inline: 0;
+  line-height: 24px;
+}
+
+.vp-annotation-popover :first-child {
+  margin-block-start: 4px;
+}
+
+.vp-annotation-popover :last-child {
+  margin-block-end: 4px;
+}
+
+.vp-annotation-popover.group :first-child {
+  margin-block-start: 8px;
+}
+
+.vp-annotation-popover.group :last-child {
+  margin-block-end: 8px;
+}

package/dist/node/index.d.ts

@@ -0,0 +1,104 @@
+import { PluginWithOptions } from "markdown-it";
+
+//#region src/node/plugin.d.ts
+/**
+ * VitePress plugin for annotation support in markdown content.
+ *
+ * VitePress 插件，用于在 markdown 内容中支持注释功能。
+ *
+ * The plugin registers annotation definition and reference rules in markdown-it,
+ * and wires up the client-side `VPAnnotation` component via `componentResolver`
+ * so that annotation references render as interactive markers that, on click,
+ * reveal a popover with the annotation content.
+ *
+ * 该插件在 markdown-it 中注册注释定义与引用规则，并通过 `componentResolver`
+ * 接入客户端 `VPAnnotation` 组件，使注释引用渲染为可交互的标记，点击后弹出
+ * 包含注释内容的浮层。
+ *
+ * Annotations can be defined inline in markdown using the syntax
+ * `[+label]: annotation content`, or provided globally through the `annotations`
+ * option. A single label can be defined multiple times — all definitions are
+ * collected and displayed as separate items in the popover. Annotation content
+ * supports full block-level markdown.
+ *
+ * 注释可以在 markdown 中通过 `[+标签]: 注释内容` 语法内联定义，也可以通过
+ * `annotations` 选项全局提供。同一标签可多次定义 —— 所有定义会被收集并作为
+ * 独立条目展示在浮层中。注释内容支持完整的块级 markdown 语法。
+ *
+ * @param annotations - Global annotations preset, a map of label to annotation
+ *   content (string or string array) / 全局注释预设，标签到注释内容
+ *   （字符串或字符串数组）的映射
+ * @example
+ * `.vitepress/config.ts` without global annotations
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import annotation from 'vitepress-plugin-annotation'
+ *
+ * export default defineConfig({
+ *   plugins: [annotation()],
+ * })
+ * ```
+ * @example
+ * `.vitepress/config.ts` with global annotations
+ * ```ts
+ * import { defineConfig } from 'vitepress-tuck'
+ * import annotation from 'vitepress-plugin-annotation'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     annotation({
+ *       HTML: 'HyperText Markup Language',
+ *     }),
+ *   ],
+ * })
+ * ```
+ * @example
+ * // Markdown usage
+ * ```md
+ * The **four great classical novels** [+novels] of Chinese literature.
+ *
+ * [+novels]:
+ *   **Romance of the Three Kingdoms** — a historical novel.
+ *
+ * [+novels]:
+ *   **Journey to the West** — a mythological adventure.
+ * ```
+ */
+declare const annotation: (options?: Record<string, string | string[]> | undefined) => import("vitepress-tuck").VitepressPlugin;
+//#endregion
+//#region src/node/markdown.d.ts
+/**
+ * Annotation plugin - Enable annotation syntax in markdown-it.
+ *
+ * 注释插件 - 在 markdown-it 中启用注释语法。
+ *
+ * Registers two rules:
+ * - A block rule (`annotationDef`) that recognizes annotation definitions of
+ *   the form `[+label]: content` and stores them in `env.annotations`.
+ *   Definitions support multi-line content via indented continuation lines,
+ *   and multiple definitions for the same label are accumulated.
+ * - An inline rule (`annotationRef`) that recognizes annotation references of
+ *   the form `[+label]` and pushes an `annotation_ref` token to be rendered
+ *   as a `<VPAnnotation>` component.
+ *
+ * 注册两条规则：
+ * - 块规则（`annotationDef`）识别 `[+标签]: 内容` 形式的注释定义，并将其
+ *   存储到 `env.annotations` 中。定义通过缩进续行支持多行内容，同一标签的
+ *   多次定义会被累加。
+ * - 行内规则（`annotationRef`）识别 `[+标签]` 形式的注释引用，并推入
+ *   `annotation_ref` 令牌，最终渲染为 `<VPAnnotation>` 组件。
+ *
+ * Definition syntax: `[+label]: annotation content`
+ * Reference syntax: `[+label]`
+ *
+ * 定义语法：`[+标签]: 注释内容`
+ * 引用语法：`[+标签]`
+ *
+ * @param md - Markdown-it instance / Markdown-it 实例
+ * @param globalAnnotations - Global annotations preset, a map of label to
+ *   annotation content (string or string array) / 全局注释预设，标签到
+ *   注释内容（字符串或字符串数组）的映射
+ */
+declare const annotationMarkdownPlugin: PluginWithOptions<Record<string, string | string[]>>;
+//#endregion
+export { annotation, annotation as default, annotationMarkdownPlugin };

package/dist/node/index.js

@@ -0,0 +1,238 @@
+import { definePlugin } from "vitepress-tuck";
+import { objectMap, toArray } from "@pengzhanbo/utils";
+import { cleanMarkdownEnv } from "vitepress-plugin-toolkit";
+//#region src/node/markdown.ts
+/**
+* Annotation definition rule
+*
+* 注释定义规则
+*
+* @param state - State block / 状态块
+* @param startLine - Start line number / 开始行号
+* @param endLine - End line number / 结束行号
+* @param silent - Silent mode / 静默模式
+* @returns Whether matched / 是否匹配
+*/
+const annotationDef = (state, startLine, endLine, silent) => {
+	const start = state.bMarks[startLine] + state.tShift[startLine];
+	const max = state.eMarks[startLine];
+	if (start + 4 > max || state.src.charAt(start) !== "[" || state.src.charAt(start + 1) !== "+") return false;
+	let pos = start + 2;
+	while (pos < max) {
+		if (state.src.charAt(pos) === " ") return false;
+		if (state.src.charAt(pos) === "]") break;
+		pos++;
+	}
+	if (pos === start + 2 || pos + 1 >= max || state.src.charAt(++pos) !== ":") return false;
+	/* istanbul ignore if -- @preserve */
+	if (silent) return true;
+	pos++;
+	const data = state.env.annotations ??= {};
+	const label = state.src.slice(start + 2, pos - 2);
+	let annotation = state.src.slice(pos, max).trim();
+	let nextLine = startLine + 1;
+	while (nextLine < endLine) {
+		const nextStart = state.bMarks[nextLine] + state.tShift[nextLine];
+		const nextMax = state.eMarks[nextLine];
+		const source = state.src.slice(nextStart, nextMax).slice(state.blkIndent).trimEnd();
+		if (state.sCount[nextLine] < state.blkIndent + 2 && source !== "") break;
+		annotation += `\n${source}`;
+		nextLine++;
+	}
+	(data[`:${label}`] ??= {
+		sources: [],
+		rendered: []
+	}).sources.push(annotation);
+	state.line = nextLine;
+	return true;
+};
+/**
+* Annotation reference rule
+*
+* 注释引用规则
+*
+* @param state - State inline / 行内状态
+* @param silent - Silent mode / 静默模式
+* @returns Whether matched / 是否匹配
+*/
+const annotationRef = (state, silent) => {
+	const start = state.pos;
+	const max = state.posMax;
+	if (start + 3 > max || typeof state.env.annotations === "undefined" || state.src.charAt(start) !== "[" || state.src.charAt(start + 1) !== "+") return false;
+	let pos = start + 2;
+	while (pos < max) {
+		if (state.src.charAt(pos) === " " || state.src.charAt(pos) === "\n") return false;
+		if (state.src.charAt(pos) === "]") break;
+		pos++;
+	}
+	if (pos === start + 2 || pos >= max) return false;
+	pos++;
+	const label = state.src.slice(start + 2, pos - 1);
+	if ((state.env.annotations?.[`:${label}`]?.sources ?? []).length === 0) return false;
+	/* istanbul ignore if -- @preserve */
+	if (!silent) {
+		const refToken = state.push("annotation_ref", "", 0);
+		refToken.meta = { label };
+	}
+	state.pos = pos;
+	state.posMax = max;
+	return true;
+};
+/**
+* Annotation plugin - Enable annotation syntax in markdown-it.
+*
+* 注释插件 - 在 markdown-it 中启用注释语法。
+*
+* Registers two rules:
+* - A block rule (`annotationDef`) that recognizes annotation definitions of
+*   the form `[+label]: content` and stores them in `env.annotations`.
+*   Definitions support multi-line content via indented continuation lines,
+*   and multiple definitions for the same label are accumulated.
+* - An inline rule (`annotationRef`) that recognizes annotation references of
+*   the form `[+label]` and pushes an `annotation_ref` token to be rendered
+*   as a `<VPAnnotation>` component.
+*
+* 注册两条规则：
+* - 块规则（`annotationDef`）识别 `[+标签]: 内容` 形式的注释定义，并将其
+*   存储到 `env.annotations` 中。定义通过缩进续行支持多行内容，同一标签的
+*   多次定义会被累加。
+* - 行内规则（`annotationRef`）识别 `[+标签]` 形式的注释引用，并推入
+*   `annotation_ref` 令牌，最终渲染为 `<VPAnnotation>` 组件。
+*
+* Definition syntax: `[+label]: annotation content`
+* Reference syntax: `[+label]`
+*
+* 定义语法：`[+标签]: 注释内容`
+* 引用语法：`[+标签]`
+*
+* @param md - Markdown-it instance / Markdown-it 实例
+* @param globalAnnotations - Global annotations preset, a map of label to
+*   annotation content (string or string array) / 全局注释预设，标签到
+*   注释内容（字符串或字符串数组）的映射
+*/
+const annotationMarkdownPlugin = (md, globalAnnotations = {}) => {
+	const annotations = objectMap(globalAnnotations, (key, value) => {
+		return [key.startsWith(":") ? key : `:${key}`, {
+			sources: toArray(value),
+			rendered: []
+		}];
+	});
+	/**
+	* Custom renderer for the `annotation_ref` token.
+	*
+	* `annotation_ref` 令牌的自定义渲染器。
+	*
+	* Renders the annotation reference as a `<VPAnnotation>` component tag. Each
+	* annotation source is rendered as block-level markdown and placed into a
+	* named slot (`#item-0`, `#item-1`, …). Rendered results are cached on the
+	* environment so that repeated references to the same label reuse the
+	* rendered output without re-rendering. The environment passed to the nested
+	* render is cleaned via `cleanMarkdownEnv` to strip `references` and
+	* `annotations`, preventing recursive annotation processing inside annotation
+	* content.
+	*
+	* 将注释引用渲染为 `<VPAnnotation>` 组件标签。每个注释源作为块级 markdown
+	* 渲染，并放入具名插槽（`#item-0`、`#item-1`、…）。渲染结果缓存在环境对象上，
+	* 使得对同一标签的重复引用可复用已渲染的结果而无需重复渲染。传递给嵌套渲染的
+	* 环境通过 `cleanMarkdownEnv` 清理，去除 `references` 和 `annotations`，
+	* 防止在注释内容中递归处理注释。
+	*
+	* When a label is not found in the inline (env) annotations, the renderer
+	* falls back to the global annotations preset.
+	*
+	* 当标签在内联（环境）注释中未找到时，渲染器回退到全局注释预设。
+	*
+	* @param tokens - Token array / token 数组
+	* @param idx - Current token index / 当前 token 索引
+	* @param _ - Render options (unused) / 渲染选项（未使用）
+	* @param env - Render environment containing annotations / 包含注释的渲染环境
+	* @returns Rendered HTML string / 渲染后的 HTML 字符串
+	*/
+	md.renderer.rules.annotation_ref = (tokens, idx, _, env) => {
+		const label = tokens[idx].meta.label;
+		/* istanbul ignore next -- @preserve */
+		const data = env.annotations[`:${label}`] || annotations[`:${label}`];
+		return `<VPAnnotation label="${md.utils.escapeHtml(label)}" :total="${data.sources.length}">${data.sources.map((source, i) => {
+			return `<template #item-${i}>${data.rendered[i] ??= md.render(source, cleanMarkdownEnv(env, ["references", "annotations"]))}</template>`;
+		}).join("\n")}</VPAnnotation>`;
+	};
+	md.inline.ruler.before("image", "annotation_ref", annotationRef);
+	md.block.ruler.before("reference", "annotation", annotationDef, { alt: ["paragraph", "reference"] });
+};
+//#endregion
+//#region src/node/plugin.ts
+/**
+* VitePress plugin for annotation support in markdown content.
+*
+* VitePress 插件，用于在 markdown 内容中支持注释功能。
+*
+* The plugin registers annotation definition and reference rules in markdown-it,
+* and wires up the client-side `VPAnnotation` component via `componentResolver`
+* so that annotation references render as interactive markers that, on click,
+* reveal a popover with the annotation content.
+*
+* 该插件在 markdown-it 中注册注释定义与引用规则，并通过 `componentResolver`
+* 接入客户端 `VPAnnotation` 组件，使注释引用渲染为可交互的标记，点击后弹出
+* 包含注释内容的浮层。
+*
+* Annotations can be defined inline in markdown using the syntax
+* `[+label]: annotation content`, or provided globally through the `annotations`
+* option. A single label can be defined multiple times — all definitions are
+* collected and displayed as separate items in the popover. Annotation content
+* supports full block-level markdown.
+*
+* 注释可以在 markdown 中通过 `[+标签]: 注释内容` 语法内联定义，也可以通过
+* `annotations` 选项全局提供。同一标签可多次定义 —— 所有定义会被收集并作为
+* 独立条目展示在浮层中。注释内容支持完整的块级 markdown 语法。
+*
+* @param annotations - Global annotations preset, a map of label to annotation
+*   content (string or string array) / 全局注释预设，标签到注释内容
+*   （字符串或字符串数组）的映射
+* @example
+* `.vitepress/config.ts` without global annotations
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import annotation from 'vitepress-plugin-annotation'
+*
+* export default defineConfig({
+*   plugins: [annotation()],
+* })
+* ```
+* @example
+* `.vitepress/config.ts` with global annotations
+* ```ts
+* import { defineConfig } from 'vitepress-tuck'
+* import annotation from 'vitepress-plugin-annotation'
+*
+* export default defineConfig({
+*   plugins: [
+*     annotation({
+*       HTML: 'HyperText Markup Language',
+*     }),
+*   ],
+* })
+* ```
+* @example
+* // Markdown usage
+* ```md
+* The **four great classical novels** [+novels] of Chinese literature.
+*
+* [+novels]:
+*   **Romance of the Three Kingdoms** — a historical novel.
+*
+* [+novels]:
+*   **Journey to the West** — a mythological adventure.
+* ```
+*/
+const annotation = definePlugin((annotations) => ({
+	name: "vitepress-plugin-annotation",
+	componentResolver: ["VPAnnotation"],
+	markdown: { config(md) {
+		md.use(annotationMarkdownPlugin, annotations);
+	} }
+}));
+//#endregion
+//#region src/node/index.ts
+var node_default = annotation;
+//#endregion
+export { annotation, annotationMarkdownPlugin, node_default as default };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "vitepress-plugin-annotation",
+  "type": "module",
+  "version": "0.7.0",
+  "description": "Add annotation support to VitePress",
+  "author": "pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/)",
+  "license": "MIT",
+  "homepage": "https://tuck.pengzhanbo.cn/plugins/annotation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pengzhanbo/vitepress-tuck.git",
+    "directory": "packages/plugin-annotation"
+  },
+  "bugs": {
+    "url": "https://github.com/pengzhanbo/vitepress-tuck/issues"
+  },
+  "keywords": [
+    "vitepress",
+    "vitepress-plugin",
+    "annotation"
+  ],
+  "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",
+    "@pengzhanbo/utils": "^3.7.3",
+    "@vueuse/core": "^14.3.0",
+    "vitepress-tuck": "0.7.0",
+    "vitepress-plugin-toolkit": "0.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  }
+}