refactor(plugin-markdown-hint): add jsdoc and update docs

docs/plugins/markdown/markdown-hint.md

@@ -33,13 +33,13 @@ export default {
 
 ## Guide
 
-By default, we support `important`, `info`, `note`, `tip`, `warning`, `danger`, `details` containers with markdown container:
+By default, we support `important`, `info`, `note`, `tip`, `warning`, `caution`, `details` containers with markdown container:
 
 :::: preview
 
 ::: tip
 
-A custom tip container with `code`, [link](#demo).
+A custom tip container with `code` and [links](https://example.com).
 
 ```js
 const a = 1
@@ -55,7 +55,7 @@ To customize the title of the container, you can add the title after the named c
 
 ::: important Custom Title
 
-A important container with customized title.
+An important container with customized title.
 
 :::
 
@@ -94,12 +94,13 @@ The plugin also provides an `alert` option to support gfm alerts:
 ### hint
 
 - Type: `boolean`
-- Details: Whether enable hint containers, enabled by default.
+- Default: `true`
+- Details: Whether to enable hint containers including important, info, note, tip, warning, caution, details.
 
 ### alert
 
 - Type: `boolean`
-- Details: Whether enable gfm alert support.
+- Details: Whether to enable GFM alert support.
 
 ### injectStyles
 
@@ -118,40 +119,40 @@ The plugin also provides an `alert` option to support gfm alerts:
 
   interface MarkdownHintPluginLocaleData {
     /**
-     * Default Title text for important block
+     * Default title text for important block
      */
     important: string
 
     /**
-     * Default Title text for note block
+     * Default title text for note block
      */
     note: string
 
     /**
-     * Default Title text for tip block
+     * Default title text for tip block
      */
     tip: string
 
     /**
-     * Default Title text for warning block
+     * Default title text for warning block
      */
     warning: string
 
     /**
-     * Default Title text for danger block
+     * Default title text for caution block
      */
     caution: string
 
     /**
-     * Default Title text for info block
+     * Default title text for info block
      */
     info: string
 
     /**
-     * Default Title text for details block
+     * Default title text for details block
      */
     details: string
   }
   ```
 
-- Details: The locales for hint container titles.
+- Details: Locale config for hint container titles.

docs/zh/plugins/markdown/markdown-hint.md

@@ -33,13 +33,13 @@ export default {
 
 ## 指南
 
-默认情况下，我们支持 `important`、`info`、`note`、`tip`、`warning`、`danger`、`details` 容器与 markdown 容器：
+默认情况下，我们支持 `important`、`info`、`note`、`tip`、`warning`、`caution`、`details` 容器与 markdown 容器：
 
 :::: preview
 
 ::: tip
 
-一个带有 `code`、[链接](#demo) 的自定义提示容器。
+一个带有 `code` 和[链接](https://example.com)的自定义提示容器。
 
 ```js
 const a = 1
@@ -94,7 +94,8 @@ const a = 1
 ### hint
 
 - 类型：`boolean`
-- 详情：是否启用提示容器，默认启用。
+- 默认值：`true`
+- 详情：是否启用提示容器，包括 important、info、note、tip、warning、caution、details。
 
 ### alert
 
@@ -154,4 +155,4 @@ const a = 1
   }
   ```
 
-  - 详情：本地化提示容器的默认标题。
+- 详情：提示容器标题的本地化配置。

plugins/markdown/plugin-markdown-hint/src/node/alert.ts

@@ -11,6 +11,14 @@ import type { MarkdownHintPluginLocaleData } from './options.js'
 export type MarkdownItAlertOptions =
   ExactLocaleConfig<MarkdownHintPluginLocaleData>
 
+/**
+ * GFM alert markdown-it plugin
+ *
+ * GFM 警告 markdown-it 插件
+ *
+ * @param md - markdown-it instance / markdown-it 实例
+ * @param options - plugin options / 插件选项
+ */
 export const alert: PluginWithOptions<MarkdownItAlertOptions> = (
   md,
   options = {},

plugins/markdown/plugin-markdown-hint/src/node/hint.ts

@@ -23,6 +23,14 @@ const CONTAINERS: MarkdownHintContainerName[] = [
   'important',
 ]
 
+/**
+ * Hint container markdown-it plugin
+ *
+ * 提示容器 markdown-it 插件
+ *
+ * @param md - markdown-it instance / markdown-it 实例
+ * @param options - plugin options / 插件选项
+ */
 export const hint: PluginWithOptions<MarkdownItHintOptions> = (
   md,
   options = {},

plugins/markdown/plugin-markdown-hint/src/node/markdownHintPlugin.ts

@@ -11,6 +11,27 @@ const PLUGIN_NAME = '@vuepress/plugin-markdown-hint'
 
 const __dirname = import.meta.dirname || getDirname(import.meta.url)
 
+/**
+ * Markdown hint plugin
+ *
+ * Markdown 提示插件
+ *
+ * @param options - plugin options / 插件选项
+ *
+ * @example
+ * ```ts
+ * import { markdownHintPlugin } from '@vuepress/plugin-markdown-hint'
+ *
+ * export default {
+ *   plugins: [
+ *     markdownHintPlugin({
+ *       hint: true,
+ *       alert: true,
+ *     }),
+ *   ],
+ * }
+ * ```
+ */
 export const markdownHintPlugin = (
   options: MarkdownHintPluginOptions,
 ): Plugin => {

plugins/markdown/plugin-markdown-hint/src/node/options.ts

@@ -3,49 +3,49 @@ import type { LocaleConfig } from 'vuepress/shared'
 
 export interface MarkdownHintPluginLocaleData {
   /**
-   * Default Title text for important block
+   * Default title text for important block
    *
    * 重要块的默认标题
    */
   important: string
 
   /**
-   * Default Title text for note block
+   * Default title text for note block
    *
    * 注释块的默认标题
    */
   note: string
 
   /**
-   * Default Title text for tip block
+   * Default title text for tip block
    *
    * 提示块的默认标题
    */
   tip: string
 
   /**
-   * Default Title text for warning block
+   * Default title text for warning block
    *
    * 注意块的默认标题
    */
   warning: string
 
   /**
-   * Default Title text for danger block
+   * Default title text for caution block
    *
    * 警告块的默认标题
    */
   caution: string
 
   /**
-   * Default Title text for info block
+   * Default title text for info block
    *
    * 信息块的默认标题
    */
   info: string
 
   /**
-   * Default Title text for details block
+   * Default title text for details block
    *
    * 详情块的默认标题
    */
@@ -56,38 +56,24 @@ export type MarkdownHintPluginLocaleConfig =
   ExactLocaleConfig<MarkdownHintPluginLocaleData>
 
 /**
- * markdown hint plugin configuration
+ * Markdown hint plugin configuration
+ *
+ * Markdown 提示插件配置
  */
 export interface MarkdownHintPluginOptions {
   /**
-   * Wether enable gfm alerts
+   * Whether to enable GFM alerts
    *
-   * 是否启用 gfm 警告
+   * 是否启用 GFM 警告
    *
    * @default false
    */
   alert?: boolean
 
   /**
-   * Whether to enable hint container including
+   * Whether to enable hint containers including important, info, note, tip, warning, caution, details
    *
-   * - important
-   * - info
-   * - note
-   * - tip
-   * - warning
-   * - caution
-   * - details
-   *
-   * 是否启用提示容器
-   *
-   * - important
-   * - info
-   * - note
-   * - tip
-   * - warning
-   * - caution
-   * - details
+   * 是否启用提示容器，包括 important、info、note、tip、warning、caution、details
    *
    * @default true
    */
@@ -96,6 +82,8 @@ export interface MarkdownHintPluginOptions {
   /**
    * Whether to inject default styles
    *
+   * 是否注入默认样式
+   *
    * @default true
    */
   injectStyles?: boolean