From 7775ead38cd3c544faf16fd4593f7e5b9f8226d4 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Wed, 4 Jun 2025 17:04:02 +0800 Subject: [PATCH] refactor(plugin-markdown-hint): add jsdoc and update docs --- docs/plugins/markdown/markdown-hint.md | 27 ++++++------ docs/zh/plugins/markdown/markdown-hint.md | 9 ++-- .../plugin-markdown-hint/src/node/alert.ts | 8 ++++ .../plugin-markdown-hint/src/node/hint.ts | 8 ++++ .../src/node/markdownHintPlugin.ts | 21 +++++++++ .../plugin-markdown-hint/src/node/options.ts | 44 +++++++------------ 6 files changed, 72 insertions(+), 45 deletions(-) diff --git a/docs/plugins/markdown/markdown-hint.md b/docs/plugins/markdown/markdown-hint.md index a00c0fc0e3..2cad024695 100644 --- a/docs/plugins/markdown/markdown-hint.md +++ b/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. diff --git a/docs/zh/plugins/markdown/markdown-hint.md b/docs/zh/plugins/markdown/markdown-hint.md index 7011390b30..48ce0c571c 100644 --- a/docs/zh/plugins/markdown/markdown-hint.md +++ b/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 } ``` - - 详情：本地化提示容器的默认标题。 +- 详情：提示容器标题的本地化配置。 diff --git a/plugins/markdown/plugin-markdown-hint/src/node/alert.ts b/plugins/markdown/plugin-markdown-hint/src/node/alert.ts index c234ac7dba..9107eb5172 100644 --- a/plugins/markdown/plugin-markdown-hint/src/node/alert.ts +++ b/plugins/markdown/plugin-markdown-hint/src/node/alert.ts @@ -11,6 +11,14 @@ import type { MarkdownHintPluginLocaleData } from './options.js' export type MarkdownItAlertOptions = ExactLocaleConfig +/** + * GFM alert markdown-it plugin + * + * GFM 警告 markdown-it 插件 + * + * @param md - markdown-it instance / markdown-it 实例 + * @param options - plugin options / 插件选项 + */ export const alert: PluginWithOptions = ( md, options = {}, diff --git a/plugins/markdown/plugin-markdown-hint/src/node/hint.ts b/plugins/markdown/plugin-markdown-hint/src/node/hint.ts index c10d632d23..128c7a8b15 100644 --- a/plugins/markdown/plugin-markdown-hint/src/node/hint.ts +++ b/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 = ( md, options = {}, diff --git a/plugins/markdown/plugin-markdown-hint/src/node/markdownHintPlugin.ts b/plugins/markdown/plugin-markdown-hint/src/node/markdownHintPlugin.ts index 1828c06e7f..97268212e5 100644 --- a/plugins/markdown/plugin-markdown-hint/src/node/markdownHintPlugin.ts +++ b/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 => { diff --git a/plugins/markdown/plugin-markdown-hint/src/node/options.ts b/plugins/markdown/plugin-markdown-hint/src/node/options.ts index 9bbd4a1c87..2bb191ad4b 100644 --- a/plugins/markdown/plugin-markdown-hint/src/node/options.ts +++ b/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 /** - * 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