From 8b481cac15cda57d58bc9cef21076d49f02fd32d Mon Sep 17 00:00:00 2001
From: Mister-Hope <mister-hope@outlook.com>
Date: Wed, 4 Jun 2025 17:31:28 +0800
Subject: [PATCH 1/2] refactor(plugin-markdown-include): add jsdoc for
 markdownIncludePlugin and options

---
 docs/plugins/markdown/markdown-include.md     | 10 ++++-----
 docs/zh/plugins/markdown/markdown-include.md  | 10 ++++-----
 .../src/node/markdownIncludePlugin.ts         | 21 +++++++++++++++++++
 .../src/node/options.ts                       |  5 +++++
 4 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/docs/plugins/markdown/markdown-include.md b/docs/plugins/markdown/markdown-include.md
index 370918c6c2..1684e7a789 100644
--- a/docs/plugins/markdown/markdown-include.md
+++ b/docs/plugins/markdown/markdown-include.md
@@ -6,7 +6,7 @@ icon: between-horizontal-end
 
 <NpmBadge package="@vuepress/plugin-markdown-include" />
 
-Add additional features to your markdown includes.
+Add markdown include features to your VuePress site.
 
 ## Usage
 
@@ -30,13 +30,13 @@ export default {
 
 Use `<!-- @include: filename -->` to include a file.
 
-To partially import the file, you can specify the range of lines to be included:
+To partially import a file, you can specify the range of lines to be included:
 
 - `<!-- @include: filename{start-end} -->`
 - `<!-- @include: filename{start-} -->`
 - `<!-- @include: filename{-end} -->`
 
-Also, you can include file region:
+Also, you can include a file region:
 
 - `<!-- @include: filename#region -->`
 
@@ -214,7 +214,7 @@ class MyClass:
     #region snippet
     def sayHello(self):
         print("Hello " + self.msg + "!")
-    #region snippet
+    #endregion snippet
 
     def sayBye(self):
         print("Bye " + self.msg + "!")
@@ -340,7 +340,7 @@ int main() {
 ### deep
 
 - Type: `boolean`
-- Details: Whether enable figure support.
+- Details: Whether deep include files in included Markdown files.
 
 ### useComment
 
diff --git a/docs/zh/plugins/markdown/markdown-include.md b/docs/zh/plugins/markdown/markdown-include.md
index e131da94a9..10f391acaa 100644
--- a/docs/zh/plugins/markdown/markdown-include.md
+++ b/docs/zh/plugins/markdown/markdown-include.md
@@ -6,7 +6,7 @@ icon: between-horizontal-end
 
 <NpmBadge package="@vuepress/plugin-markdown-include" />
 
-向你的 VuePress 添加导入文件功能。
+为你的 VuePress 站点添加 Markdown 导入功能。
 
 ## 使用方法
 
@@ -30,13 +30,13 @@ export default {
 
 使用 `<!-- @include: filename -->` 导入文件。
 
-如果要部分导入文件，你可以指定导入的行数
+如果要部分导入文件，你可以指定导入的行数：
 
 - `<!-- @include: filename{start-end} -->`
 - `<!-- @include: filename{start-} -->`
 - `<!-- @include: filename{-end} -->`
 
-同时你也可以导入文件区域:
+同时你也可以导入文件区域：
 
 - `<!-- @include: filename#region -->`
 
@@ -214,7 +214,7 @@ class MyClass:
     #region snippet
     def sayHello(self):
         print("Hello " + self.msg + "!")
-    #region snippet
+    #endregion snippet
 
     def sayBye(self):
         print("Bye " + self.msg + "!")
@@ -340,7 +340,7 @@ int main() {
 ### deep
 
 - 类型：`boolean`
-- 详情：是否启用图片 Figure 支持。
+- 详情：是否深度导入包含的 Markdown 文件。
 
 ### useComment
 
diff --git a/plugins/markdown/plugin-markdown-include/src/node/markdownIncludePlugin.ts b/plugins/markdown/plugin-markdown-include/src/node/markdownIncludePlugin.ts
index 7afcecd233..ff8369bd95 100644
--- a/plugins/markdown/plugin-markdown-include/src/node/markdownIncludePlugin.ts
+++ b/plugins/markdown/plugin-markdown-include/src/node/markdownIncludePlugin.ts
@@ -6,6 +6,27 @@ import type { MarkdownEnv } from 'vuepress/markdown'
 import { path } from 'vuepress/utils'
 import type { MarkdownIncludePluginOptions } from './options.js'
 
+/**
+ * Markdown include plugin
+ *
+ * Markdown 导入插件
+ *
+ * @param options - Plugin options / 插件选项
+ *
+ * @example
+ * ```ts
+ * import { markdownIncludePlugin } from '@vuepress/plugin-markdown-include'
+ *
+ * export default {
+ *   plugins: [
+ *     markdownIncludePlugin({
+ *       deep: true,
+ *       useComment: true,
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
 export const markdownIncludePlugin =
   (options: MarkdownIncludePluginOptions): Plugin =>
   (app) => {
diff --git a/plugins/markdown/plugin-markdown-include/src/node/options.ts b/plugins/markdown/plugin-markdown-include/src/node/options.ts
index 90ff319002..0d2ec4ee1f 100644
--- a/plugins/markdown/plugin-markdown-include/src/node/options.ts
+++ b/plugins/markdown/plugin-markdown-include/src/node/options.ts
@@ -1,5 +1,10 @@
 import type { MarkdownItIncludeOptions } from '@mdit/plugin-include'
 
+/**
+ * Options for @vuepress/plugin-markdown-include
+ *
+ * @vuepress/plugin-markdown-include 插件的选项
+ */
 export type MarkdownIncludePluginOptions = Omit<
   MarkdownItIncludeOptions,
   'currentPath'

From 9db15a833af300ca0747e101f7da1df4c5480413 Mon Sep 17 00:00:00 2001
From: Mister-Hope <mister-hope@outlook.com>
Date: Wed, 4 Jun 2025 17:52:53 +0800
Subject: [PATCH 2/2] docs: improve docs

---
 docs/plugins/markdown/markdown-include.md    | 2 +-
 docs/zh/plugins/markdown/markdown-include.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/plugins/markdown/markdown-include.md b/docs/plugins/markdown/markdown-include.md
index 1684e7a789..f31c19616f 100644
--- a/docs/plugins/markdown/markdown-include.md
+++ b/docs/plugins/markdown/markdown-include.md
@@ -340,7 +340,7 @@ int main() {
 ### deep
 
 - Type: `boolean`
-- Details: Whether deep include files in included Markdown files.
+- Details: Whether to recursively include files referenced in included Markdown files.
 
 ### useComment
 
diff --git a/docs/zh/plugins/markdown/markdown-include.md b/docs/zh/plugins/markdown/markdown-include.md
index 10f391acaa..5ea9d92815 100644
--- a/docs/zh/plugins/markdown/markdown-include.md
+++ b/docs/zh/plugins/markdown/markdown-include.md
@@ -340,7 +340,7 @@ int main() {
 ### deep
 
 - 类型：`boolean`
-- 详情：是否深度导入包含的 Markdown 文件。
+- 详情：是否递归包含被包含的 Markdown 文件中引用的文件。
 
 ### useComment