From de34550e158e5f567f18dd2c5fbebb84c7022f67 Mon Sep 17 00:00:00 2001
From: Mister-Hope <mister-hope@outlook.com>
Date: Wed, 4 Jun 2025 16:35:22 +0800
Subject: [PATCH 1/2] refactor(plugin-markdown-container): add jsdoc

---
 docs/plugins/markdown/markdown-container.md   |   6 +-
 .../zh/plugins/markdown/markdown-container.md |  26 ++--
 .../src/node/index.ts                         |   1 +
 .../src/node/markdownContainerPlugin.ts       | 101 +++-----------
 .../src/node/options.ts                       | 127 ++++++++++++++++++
 5 files changed, 167 insertions(+), 94 deletions(-)
 create mode 100644 plugins/markdown/plugin-markdown-container/src/node/options.ts

diff --git a/docs/plugins/markdown/markdown-container.md b/docs/plugins/markdown/markdown-container.md
index 57ff6fb5e4..847e8b6ff5 100644
--- a/docs/plugins/markdown/markdown-container.md
+++ b/docs/plugins/markdown/markdown-container.md
@@ -10,8 +10,6 @@ Register markdown custom containers in your VuePress site.
 
 This plugin simplifies the use of [markdown-it-container](https://github.com/markdown-it/markdown-it-container), but also retains its original capabilities.
 
-The [Custom Containers](../../themes/default/markdown.md#custom-containers) of default theme is powered by this plugin.
-
 ## Usage
 
 ```bash
@@ -51,6 +49,7 @@ This plugin can be used multiple times to support different types of containers.
 ### type
 
 - Type: `string`
+- Required: Yes
 
 - Details:
 
@@ -88,7 +87,7 @@ export default {
 }
 ```
 
-- Also see:
+- Reference:
   - [Guide > I18n](https://vuejs.press/guide/i18n.html)
 
 ### before
@@ -163,6 +162,7 @@ type MarkdownItContainerRenderFunction = (
 ### marker
 
 - Type: `string`
+- Default: `':'`
 
 - Details:
 
diff --git a/docs/zh/plugins/markdown/markdown-container.md b/docs/zh/plugins/markdown/markdown-container.md
index f5348b6177..0b7442cd75 100644
--- a/docs/zh/plugins/markdown/markdown-container.md
+++ b/docs/zh/plugins/markdown/markdown-container.md
@@ -10,8 +10,6 @@ icon: package
 
 该插件简化了 [markdown-it-container](https://github.com/markdown-it/markdown-it-container) 的使用方法，但同时也保留了其原本的能力。
 
-默认主题的 [自定义容器](../../themes/default/markdown.md#自定义容器) 就是由该插件支持的。
-
 ## 使用方法
 
 ```bash
@@ -40,7 +38,7 @@ export default {
 
 - `type` 是必需的，应通过 [type](#type) 配置项来指定。
 - `info` 是可选的，其默认值可以通过 [locales](#locales) 的 `defaultInfo` 配置项来指定。
-- `content` 可是任何合法的 Markdown 内容。
+- `content` 可以是任何合法的 Markdown 内容。
 
 ::: tip
 该插件可以被多次使用，以便支持不同类型的容器。
@@ -50,7 +48,9 @@ export default {
 
 ### type
 
-- 类型： `string`
+- 类型：`string`
+
+- 必填：是
 
 - 详情：
 
@@ -60,13 +60,13 @@ export default {
 
 ### locales
 
-- 类型： `Record<string, { defaultInfo: string }>`
+- 类型：`Record<string, { defaultInfo: string }>`
 
 - 详情：
 
-  容器在不同 locales 下的默认 `info` 。
+  容器在不同 locales 下的默认 `info`。
 
-  如果没有指定该配置项，默认 `info` 会使用大写的 [type](#type) 。
+  如果没有指定该配置项，默认 `info` 会使用大写的 [type](#type)。
 
 - 示例：
 
@@ -93,7 +93,7 @@ export default {
 
 ### before
 
-- 类型： `(info: string) => string`
+- 类型：`(info: string) => string`
 
 - 默认值：
 
@@ -114,7 +114,7 @@ export default {
 
 ### after
 
-- 类型： `(info: string) => string`
+- 类型：`(info: string) => string`
 
 - 默认值：
 
@@ -150,11 +150,11 @@ type MarkdownItContainerRenderFunction = (
 
   [markdown-it-container](https://github.com/markdown-it/markdown-it-container#api) 的 `render` 配置项。
 
-  该插件使用了一个默认的 `render` 函数。但如果你指定了该配置项，那么默认的 `render` 函数就会被替换掉，此时 [locales](#locales) 、 [before](#before) 和 [after](#after) 配置项都会被忽略。
+  该插件使用了一个默认的 `render` 函数。但如果你指定了该配置项，那么默认的 `render` 函数就会被替换掉，此时 [locales](#locales)、[before](#before) 和 [after](#after) 配置项都会被忽略。
 
 ### validate
 
-- 类型： `(params: string) => boolean`
+- 类型：`(params: string) => boolean`
 
 - 详情：
 
@@ -162,7 +162,9 @@ type MarkdownItContainerRenderFunction = (
 
 ### marker
 
-- 类型： `string`
+- 类型：`string`
+
+- 默认值：`':'`
 
 - 详情：
 
diff --git a/plugins/markdown/plugin-markdown-container/src/node/index.ts b/plugins/markdown/plugin-markdown-container/src/node/index.ts
index cb48cf38a6..7ea8ce8b78 100644
--- a/plugins/markdown/plugin-markdown-container/src/node/index.ts
+++ b/plugins/markdown/plugin-markdown-container/src/node/index.ts
@@ -1 +1,2 @@
 export * from './markdownContainerPlugin.js'
+export type * from './options.js'
diff --git a/plugins/markdown/plugin-markdown-container/src/node/markdownContainerPlugin.ts b/plugins/markdown/plugin-markdown-container/src/node/markdownContainerPlugin.ts
index c5f9e181f5..c667514696 100644
--- a/plugins/markdown/plugin-markdown-container/src/node/markdownContainerPlugin.ts
+++ b/plugins/markdown/plugin-markdown-container/src/node/markdownContainerPlugin.ts
@@ -1,90 +1,33 @@
-import type Renderer from 'markdown-it/lib/renderer.mjs'
-import type Token from 'markdown-it/lib/token.mjs'
 // eslint-disable-next-line import/no-rename-default
 import container from 'markdown-it-container'
 import type { Plugin, PluginObject } from 'vuepress/core'
-import type { MarkdownEnv } from 'vuepress/markdown'
-import type { LocaleConfig } from 'vuepress/shared'
 import { ensureLeadingSlash, resolveLocalePath } from 'vuepress/shared'
 import { colors, logger } from 'vuepress/utils'
+import type {
+  MarkdownContainerPluginOptions,
+  RenderPlaceFunction,
+} from './options.js'
 
 /**
- * Options for markdown-it-container
+ * Create markdown container plugin
+ *
+ * 创建 markdown 容器插件
+ *
+ * @param options - Plugin options / 插件配置项
+ *
+ * @example
+ * ```ts
+ * import { markdownContainerPlugin } from '@vuepress/plugin-markdown-container'
+ *
+ * markdownContainerPlugin({
+ *   type: 'tip',
+ *   locales: {
+ *     '/': { defaultInfo: 'TIP' },
+ *     '/zh/': { defaultInfo: '提示' },
+ *   },
+ * })
+ * ```
  */
-export interface MarkdownItContainerOptions {
-  /**
-   * The marker of the container syntax
-   *
-   * @default ':'
-   * @see https://github.com/markdown-it/markdown-it-container#api
-   */
-  marker?: string
-
-  /**
-   * Renderer function for opening / closing tokens
-   *
-   * @see https://github.com/markdown-it/markdown-it-container#api
-   */
-  render?: MarkdownItContainerRenderFunction
-
-  /**
-   * Function to validate tail after opening marker, should return `true` on success
-   */
-  validate?: (params: string) => boolean
-}
-
-export type MarkdownItContainerRenderFunction = (
-  tokens: Token[],
-  index: number,
-  options: unknown,
-  env: MarkdownEnv,
-  self: Renderer,
-) => string
-
-export type RenderPlaceFunction = (info: string) => string
-
-/**
- * Options for @vuepress/plugin-markdown-container
- */
-export interface MarkdownContainerPluginOptions
-  extends MarkdownItContainerOptions {
-  /**
-   * The type of the container
-   *
-   * It would be used as the `name` of the container
-   *
-   * @see https://github.com/markdown-it/markdown-it-container#api
-   */
-  type: string
-
-  /**
-   * Locales config for container
-   */
-  locales?: LocaleConfig<{
-    /**
-     * Default info of the container
-     *
-     * If this option is not specified, the default info will fallback to the
-     * uppercase of the `type` option
-     */
-    defaultInfo: string
-  }>
-
-  /**
-   * A function to render the starting tag of the container.
-   *
-   * This option will not take effect if you don't specify the `after` option.
-   */
-  before?: RenderPlaceFunction
-
-  /**
-   * A function to render the ending tag of the container.
-   *
-   * This option will not take effect if you don't specify the `before` option.
-   */
-  after?: RenderPlaceFunction
-}
-
 export const markdownContainerPlugin = ({
   // plugin options
   type,
diff --git a/plugins/markdown/plugin-markdown-container/src/node/options.ts b/plugins/markdown/plugin-markdown-container/src/node/options.ts
new file mode 100644
index 0000000000..7585d797c7
--- /dev/null
+++ b/plugins/markdown/plugin-markdown-container/src/node/options.ts
@@ -0,0 +1,127 @@
+import type Renderer from 'markdown-it/lib/renderer.mjs'
+import type Token from 'markdown-it/lib/token.mjs'
+import type { MarkdownEnv } from 'vuepress/markdown'
+import type { LocaleConfig } from 'vuepress/shared'
+
+/**
+ * Options for markdown-it-container
+ *
+ * markdown-it-container 的配置项
+ */
+export interface MarkdownItContainerOptions {
+  /**
+   * The marker of the container syntax
+   *
+   * 容器语法的标记符
+   *
+   * @default ':'
+   * @see https://github.com/markdown-it/markdown-it-container#api
+   */
+  marker?: string
+
+  /**
+   * Renderer function for opening / closing tokens
+   *
+   * 用于渲染开始/结束标记的函数
+   *
+   * @see https://github.com/markdown-it/markdown-it-container#api
+   */
+  render?: MarkdownItContainerRenderFunction
+
+  /**
+   * Function to validate tail after opening marker, should return `true` on success
+   *
+   * 用于验证开始标记后内容的函数，成功时应返回 `true`
+   */
+  validate?: (params: string) => boolean
+}
+
+/**
+ * Renderer function for markdown-it-container
+ *
+ * markdown-it-container 的渲染函数
+ *
+ * @param tokens - Token array / Token 数组
+ * @param index - Current token index / 当前 token 索引
+ * @param options - Options object / 配置对象
+ * @param env - Markdown environment / Markdown 环境
+ * @param self - Renderer instance / 渲染器实例
+ */
+export type MarkdownItContainerRenderFunction = (
+  tokens: Token[],
+  index: number,
+  options: unknown,
+  env: MarkdownEnv,
+  self: Renderer,
+) => string
+
+/**
+ * Function to render container parts
+ *
+ * 渲染容器部分的函数
+ *
+ * @param info - Container info string / 容器信息字符串
+ */
+export type RenderPlaceFunction = (info: string) => string
+
+/**
+ * Options for @vuepress/plugin-markdown-container
+ *
+ * @vuepress/plugin-markdown-container 的配置项
+ */
+export interface MarkdownContainerPluginOptions
+  extends MarkdownItContainerOptions {
+  /**
+   * The type of the container
+   *
+   * It would be used as the `name` of the container
+   *
+   * 容器的类型
+   *
+   * 它将被用作容器的 `name` 参数
+   *
+   * @see https://github.com/markdown-it/markdown-it-container#api
+   */
+  type: string
+
+  /**
+   * Locales config for container
+   *
+   * 容器的多语言配置
+   */
+  locales?: LocaleConfig<{
+    /**
+     * Default info of the container
+     *
+     * If this option is not specified, the default info will fallback to the
+     * uppercase of the `type` option
+     *
+     * 容器的默认信息
+     *
+     * 如果未指定此选项，默认信息将回退到 `type` 选项的大写形式
+     */
+    defaultInfo: string
+  }>
+
+  /**
+   * A function to render the starting tag of the container.
+   *
+   * This option will not take effect if you don't specify the `after` option.
+   *
+   * 用于渲染容器开始标签的函数
+   *
+   * 如果未指定 `after` 选项，此选项将不会生效
+   */
+  before?: RenderPlaceFunction
+
+  /**
+   * A function to render the ending tag of the container.
+   *
+   * This option will not take effect if you don't specify the `before` option.
+   *
+   * 用于渲染容器结束标签的函数
+   *
+   * 如果未指定 `before` 选项，此选项将不会生效
+   */
+  after?: RenderPlaceFunction
+}

From f95335aed0219244f89e68516e55616d70b8621e Mon Sep 17 00:00:00 2001
From: Mister-Hope <mister-hope@outlook.com>
Date: Wed, 4 Jun 2025 16:39:45 +0800
Subject: [PATCH 2/2] chore: tweaks

---
 docs/plugins/markdown/markdown-container.md   | 39 ++++++++----------
 .../zh/plugins/markdown/markdown-container.md | 40 ++++++++-----------
 2 files changed, 34 insertions(+), 45 deletions(-)

diff --git a/docs/plugins/markdown/markdown-container.md b/docs/plugins/markdown/markdown-container.md
index 847e8b6ff5..3f4efff188 100644
--- a/docs/plugins/markdown/markdown-container.md
+++ b/docs/plugins/markdown/markdown-container.md
@@ -60,6 +60,7 @@ This plugin can be used multiple times to support different types of containers.
 ### locales
 
 - Type: `Record<string, { defaultInfo: string }>`
+- Default: `{}`
 
 - Details:
 
@@ -93,15 +94,12 @@ export default {
 ### before
 
 - Type: `(info: string) => string`
-
 - Default:
 
-<!-- prettier-ignore-start -->
-```ts
-(info: string): string =>
-  `<div class="custom-container ${type}">${info ? `<p class="custom-container-title">${info}</p>` : ''}\n`
-```
-<!-- prettier-ignore-end -->
+  ```ts
+  ;(info: string): string =>
+    `<div class="custom-container ${type}">${info ? `<p class="custom-container-title">${info}</p>` : ''}\n`
+  ```
 
 - Details:
 
@@ -114,14 +112,11 @@ export default {
 ### after
 
 - Type: `(info: string) => string`
-
 - Default:
 
-<!-- prettier-ignore-start -->
-```ts
-(): string => '</div>\n'
-```
-<!-- prettier-ignore-end -->
+  ```ts
+  ;(): string => '</div>\n'
+  ```
 
 - Details:
 
@@ -135,15 +130,15 @@ export default {
 
 - Type:
 
-```ts
-type MarkdownItContainerRenderFunction = (
-  tokens: Token[],
-  index: number,
-  options: unknown,
-  env: MarkdownEnv,
-  self: Renderer,
-) => string
-```
+  ```ts
+  type MarkdownItContainerRenderFunction = (
+    tokens: Token[],
+    index: number,
+    options: unknown,
+    env: MarkdownEnv,
+    self: Renderer,
+  ) => string
+  ```
 
 - Details:
 
diff --git a/docs/zh/plugins/markdown/markdown-container.md b/docs/zh/plugins/markdown/markdown-container.md
index 0b7442cd75..ec51b995f3 100644
--- a/docs/zh/plugins/markdown/markdown-container.md
+++ b/docs/zh/plugins/markdown/markdown-container.md
@@ -49,7 +49,6 @@ export default {
 ### type
 
 - 类型：`string`
-
 - 必填：是
 
 - 详情：
@@ -61,6 +60,7 @@ export default {
 ### locales
 
 - 类型：`Record<string, { defaultInfo: string }>`
+- 默认值：`{}`
 
 - 详情：
 
@@ -94,15 +94,12 @@ export default {
 ### before
 
 - 类型：`(info: string) => string`
-
 - 默认值：
 
-<!-- prettier-ignore-start -->
-```ts
-(info: string): string =>
-  `<div class="custom-container ${type}">${info ? `<p class="custom-container-title">${info}</p>` : ''}\n`
-```
-<!-- prettier-ignore-end -->
+  ```ts
+  ;(info: string): string =>
+    `<div class="custom-container ${type}">${info ? `<p class="custom-container-title">${info}</p>` : ''}\n`
+  ```
 
 - 详情：
 
@@ -115,14 +112,11 @@ export default {
 ### after
 
 - 类型：`(info: string) => string`
-
 - 默认值：
 
-<!-- prettier-ignore-start -->
-```ts
-(): string => '</div>\n'
-```
-<!-- prettier-ignore-end -->
+  ```ts
+  ;(): string => '</div>\n'
+  ```
 
 - 详情：
 
@@ -136,15 +130,15 @@ export default {
 
 - 类型：
 
-```ts
-type MarkdownItContainerRenderFunction = (
-  tokens: Token[],
-  index: number,
-  options: unknown,
-  env: MarkdownEnv,
-  self: Renderer,
-) => string
-```
+  ```ts
+  type MarkdownItContainerRenderFunction = (
+    tokens: Token[],
+    index: number,
+    options: unknown,
+    env: MarkdownEnv,
+    self: Renderer,
+  ) => string
+  ```
 
 - 详情：