From 342e62c047ad716cd967e8ed947043655607e9f9 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Wed, 4 Jun 2025 20:22:28 +0800 Subject: [PATCH] docs(highlighter-helper): add jsdoc --- .../client/composables/setupCollapsedLines.ts | 21 ++++++++++++ .../src/node/codeBlockTitle/options.ts | 21 ++++++++++++ .../src/node/codeBlockTitle/plugin.ts | 22 ++++++++++++ .../src/node/collapsedLines/options.ts | 19 ++++++++++- .../src/node/collapsedLines/plugin.ts | 18 ++++++++++ .../collapsedLines/resolveCollapsedLine.ts | 34 +++++++++++++++++++ .../src/node/lineNumbers/options.ts | 25 ++++++++++++-- .../src/node/lineNumbers/plugin.ts | 18 ++++++++++ .../node/lineNumbers/resolveLineNumbers.ts | 17 ++++++++++ .../src/node/utils/resolveAttr.ts | 16 +++++++++ .../highlighter-helper/src/node/whitespace.ts | 32 +++++++++++++++++ 11 files changed, 240 insertions(+), 3 deletions(-) diff --git a/tools/highlighter-helper/src/client/composables/setupCollapsedLines.ts b/tools/highlighter-helper/src/client/composables/setupCollapsedLines.ts index 6a410569dd..370e410c54 100644 --- a/tools/highlighter-helper/src/client/composables/setupCollapsedLines.ts +++ b/tools/highlighter-helper/src/client/composables/setupCollapsedLines.ts @@ -1,5 +1,26 @@ import { useEventListener } from '@vueuse/core' +/** + * Setup collapsed lines functionality for code blocks + * + * 为代码块设置折叠行功能 + * + * @param options - Setup options / 设置选项 + * @param options.selector - CSS selector for collapsed lines elements / 折叠行元素的 CSS 选择器 + * + * @example + * ```ts + * import { setupCollapsedLines } from '@vuepress/highlighter-helper/client' + * + * // Use default selector + * setupCollapsedLines() + * + * // Use custom selector + * setupCollapsedLines({ + * selector: '.my-collapsed-lines' + * }) + * ``` + */ export const setupCollapsedLines = ({ selector = 'div[class*="language-"].has-collapsed-lines > .collapsed-lines', }: { selector?: string } = {}): void => { diff --git a/tools/highlighter-helper/src/node/codeBlockTitle/options.ts b/tools/highlighter-helper/src/node/codeBlockTitle/options.ts index 0aa29ff07b..323c2a8855 100644 --- a/tools/highlighter-helper/src/node/codeBlockTitle/options.ts +++ b/tools/highlighter-helper/src/node/codeBlockTitle/options.ts @@ -1,12 +1,33 @@ +/** + * Code block title render function + * + * 代码块标题渲染函数 + * + * @param title - The title to render / 要渲染的标题 + * @param code - The code block HTML / 代码块 HTML + * @returns The rendered HTML / 渲染后的 HTML + */ export type CodeBlockTitleRender = (title: string, code: string) => string +/** + * Options for markdown-it code block title plugin + * + * markdown-it 代码块标题插件选项 + */ export interface MarkdownItCodeBlockTitleOptions { /** * Whether to render the title of the code block * + * 是否渲染代码块的标题 + * * - If `true`, enable the title render of the code block * - If `false`, disable the title render of the code block * - If `Function`, custom title render + * + * - 如果是 `true`，启用代码块标题渲染 + * - 如果是 `false`，禁用代码块标题渲染 + * - 如果是 `Function`，自定义标题渲染 + * * @default true */ codeBlockTitle?: CodeBlockTitleRender | boolean diff --git a/tools/highlighter-helper/src/node/codeBlockTitle/plugin.ts b/tools/highlighter-helper/src/node/codeBlockTitle/plugin.ts index 19b2f1f385..36c4bdfe44 100644 --- a/tools/highlighter-helper/src/node/codeBlockTitle/plugin.ts +++ b/tools/highlighter-helper/src/node/codeBlockTitle/plugin.ts @@ -6,6 +6,11 @@ import type { MarkdownItCodeBlockTitleOptions, } from './options.js' +/** + * Default title render function + * + * 默认标题渲染函数 + */ const defaultTitleRender: CodeBlockTitleRender = (title, code) => `\
@@ -15,6 +20,23 @@ const defaultTitleRender: CodeBlockTitleRender = (title, code) => ${code}
` +/** + * Add code block title functionality to markdown-it + * + * 为 markdown-it 添加代码块标题功能 + * + * @param md - The markdown-it instance / markdown-it 实例 + * @param options - Plugin options / 插件选项 + * + * @example + * ```ts + * import { codeBlockTitle } from '@vuepress/highlighter-helper' + * + * md.use(codeBlockTitle, { + * codeBlockTitle: true + * }) + * ``` + */ export const codeBlockTitle = ( md: Markdown, { diff --git a/tools/highlighter-helper/src/node/collapsedLines/options.ts b/tools/highlighter-helper/src/node/collapsedLines/options.ts index e8b1eb66ee..16314c0eb4 100644 --- a/tools/highlighter-helper/src/node/collapsedLines/options.ts +++ b/tools/highlighter-helper/src/node/collapsedLines/options.ts @@ -1,16 +1,33 @@ +/** + * Options for markdown-it collapsed lines plugin + * + * markdown-it 折叠行插件选项 + */ export interface MarkdownItCollapsedLinesOptions { /** - * Whether to collapse code blocks when they exceed a certain number of lines, + * Whether to collapse code blocks when they exceed a certain number of lines + * + * 当代码块超过一定行数时是否折叠 * * - If `number`, collapse starts from line `number`. * - If `true`, collapse starts from line 15 by default. * - If `false`, do not enable code block collapsing globally, but you can enable it for individual code blocks using `:collapsed-lines` * - If `'disable'`, Completely disable code block collapsing + * + * - 如果是 `number`，从第 `number` 行开始折叠 + * - 如果是 `true`，默认从第 15 行开始折叠 + * - 如果是 `false`，不全局启用代码块折叠，但你可以为单个代码块使用 `:collapsed-lines` 启用 + * - 如果是 `'disable'`，完全禁用代码块折叠 + * * @default 'disable' */ collapsedLines?: boolean | number | 'disable' /** + * Whether to remove the last line + * + * 是否移除最后一行 + * * @default false */ removeLastLine?: boolean diff --git a/tools/highlighter-helper/src/node/collapsedLines/plugin.ts b/tools/highlighter-helper/src/node/collapsedLines/plugin.ts index f08ee2b4e6..adae65fd83 100644 --- a/tools/highlighter-helper/src/node/collapsedLines/plugin.ts +++ b/tools/highlighter-helper/src/node/collapsedLines/plugin.ts @@ -2,6 +2,24 @@ import type { Markdown } from 'vuepress/markdown' import type { MarkdownItCollapsedLinesOptions } from './options.js' import { resolveCollapsedLines } from './resolveCollapsedLine.js' +/** + * Add collapsed lines functionality to code blocks in markdown-it + * + * 为 markdown-it 中的代码块添加折叠行功能 + * + * @param md - The markdown-it instance / markdown-it 实例 + * @param options - Plugin options / 插件选项 + * + * @example + * ```ts + * import { collapsedLines } from '@vuepress/highlighter-helper' + * + * md.use(collapsedLines, { + * collapsedLines: 15, + * removeLastLine: false + * }) + * ``` + */ export const collapsedLines = ( md: Markdown, { diff --git a/tools/highlighter-helper/src/node/collapsedLines/resolveCollapsedLine.ts b/tools/highlighter-helper/src/node/collapsedLines/resolveCollapsedLine.ts index dddc8c7c49..fd32a3cbb3 100644 --- a/tools/highlighter-helper/src/node/collapsedLines/resolveCollapsedLine.ts +++ b/tools/highlighter-helper/src/node/collapsedLines/resolveCollapsedLine.ts @@ -1,9 +1,43 @@ +/** + * Regular expression to match `:collapsed-lines` directive in code block info + * + * 匹配代码块信息中 `:collapsed-lines` 指令的正则表达式 + */ const COLLAPSED_LINES_REGEXP = /:collapsed-lines\b/ + +/** + * Regular expression to match `:collapsed-lines=num` directive in code block info + * + * 匹配代码块信息中 `:collapsed-lines=num` 指令的正则表达式 + */ const COLLAPSED_LINES_START_REGEXP = /:collapsed-lines=(\d+)\b/ + +/** + * Regular expression to match `:no-collapsed-lines` directive in code block info + * + * 匹配代码块信息中 `:no-collapsed-lines` 指令的正则表达式 + */ const NO_COLLAPSED_LINES_REGEXP = /:no-collapsed-lines\b/ /** * Resolve the `:collapsed-lines` `:collapsed-lines=num` / `:no-collapsed-lines` mark from token info + * + * 从 token 信息中解析 `:collapsed-lines` `:collapsed-lines=num` / `:no-collapsed-lines` 标记 + * + * @param info - Code block info string / 代码块信息字符串 + * @returns Collapsed lines configuration / 折叠行配置 + * - `number` - Start line number for collapsing / 折叠起始行号 + * - `true` - Enable collapsed lines / 启用折叠行 + * - `false` - Disable collapsed lines / 禁用折叠行 + * - `null` - No configuration found / 未找到配置 + * + * @example + * ```ts + * resolveCollapsedLines('js :collapsed-lines') // true + * resolveCollapsedLines('js :collapsed-lines=20') // 20 + * resolveCollapsedLines('js :no-collapsed-lines') // false + * resolveCollapsedLines('js') // null + * ``` */ export function resolveCollapsedLines(info: string): boolean | number | null { const lines = COLLAPSED_LINES_START_REGEXP.exec(info)?.[1] diff --git a/tools/highlighter-helper/src/node/lineNumbers/options.ts b/tools/highlighter-helper/src/node/lineNumbers/options.ts index 994dae796f..14e51ab7ef 100644 --- a/tools/highlighter-helper/src/node/lineNumbers/options.ts +++ b/tools/highlighter-helper/src/node/lineNumbers/options.ts @@ -1,25 +1,46 @@ +/** + * Options for markdown-it line numbers plugin + * + * markdown-it 行号插件选项 + */ export interface MarkdownItLineNumbersOptions { /** * Show line numbers in code blocks * + * 在代码块中显示行号 + * * - If `number`, show line numbers with code block lines not less than `number`. * - If `true`, show line number always * - If `false`, do not enable line numbers globally, but you can enable it for individual code blocks using `:line-numbers` * - If `'disable'`, Completely disable line number + * + * - 如果是 `number`，当代码块行数不少于该数字时显示行号 + * - 如果是 `true`，总是显示行号 + * - 如果是 `false`，不全局启用行号，但你可以为单个代码块使用 `:line-numbers` 启用 + * - 如果是 `'disable'`，完全禁用行号 + * * @default 'disable' */ lineNumbers?: boolean | number | 'disable' /** + * Whether to remove the last line + * + * 是否移除最后一行 + * * @default false */ removeLastLine?: boolean /** * Custom resolving function that whether to enable line numbers for a single code block + * + * 自定义解析函数，用于决定是否为单个代码块启用行号 + * + * @param info - Code block info string / 代码块信息字符串 * @returns `boolean | undefined` - * - `boolean` - Whether to enable line numbers - * - `undefined` - built-in resolving + * - `boolean` - Whether to enable line numbers / 是否启用行号 + * - `undefined` - built-in resolving / 使用内置解析 */ resolveLineNumbers?: (info: string) => boolean | undefined } diff --git a/tools/highlighter-helper/src/node/lineNumbers/plugin.ts b/tools/highlighter-helper/src/node/lineNumbers/plugin.ts index 8058714699..8bfb9f3d6f 100644 --- a/tools/highlighter-helper/src/node/lineNumbers/plugin.ts +++ b/tools/highlighter-helper/src/node/lineNumbers/plugin.ts @@ -2,6 +2,24 @@ import type { Markdown } from 'vuepress/markdown' import type { MarkdownItLineNumbersOptions } from './options.js' import { resolveLineNumbers } from './resolveLineNumbers.js' +/** + * Add line numbers to code blocks in markdown-it + * + * 为 markdown-it 中的代码块添加行号 + * + * @param md - The markdown-it instance / markdown-it 实例 + * @param options - Plugin options / 插件选项 + * + * @example + * ```ts + * import { lineNumbers } from '@vuepress/highlighter-helper' + * + * md.use(lineNumbers, { + * lineNumbers: true, + * removeLastLine: false + * }) + * ``` + */ export const lineNumbers = ( md: Markdown, { diff --git a/tools/highlighter-helper/src/node/lineNumbers/resolveLineNumbers.ts b/tools/highlighter-helper/src/node/lineNumbers/resolveLineNumbers.ts index e94d3a8075..84dda73206 100644 --- a/tools/highlighter-helper/src/node/lineNumbers/resolveLineNumbers.ts +++ b/tools/highlighter-helper/src/node/lineNumbers/resolveLineNumbers.ts @@ -4,6 +4,23 @@ const LINE_NUMBERS_START_REGEXP = /:line-numbers=(\d+)\b/ /** * Resolve the `:line-numbers` `:line-numbers=num` / `:no-line-numbers` mark from token info + * + * 从 token 信息中解析 `:line-numbers` `:line-numbers=num` / `:no-line-numbers` 标记 + * + * @param info - Code block info string / 代码块信息字符串 + * @returns Line numbers configuration / 行号配置 + * - `number` - Start line number / 起始行号 + * - `true` - Enable line numbers / 启用行号 + * - `false` - Disable line numbers / 禁用行号 + * - `null` - No configuration found / 未找到配置 + * + * @example + * ```ts + * resolveLineNumbers('js :line-numbers') // true + * resolveLineNumbers('js :line-numbers=10') // 10 + * resolveLineNumbers('js :no-line-numbers') // false + * resolveLineNumbers('js') // null + * ``` */ export const resolveLineNumbers = (info: string): boolean | number | null => { const lineNumber = LINE_NUMBERS_START_REGEXP.exec(info)?.[1] diff --git a/tools/highlighter-helper/src/node/utils/resolveAttr.ts b/tools/highlighter-helper/src/node/utils/resolveAttr.ts index 2d86b3d0f1..1b9c9c13eb 100644 --- a/tools/highlighter-helper/src/node/utils/resolveAttr.ts +++ b/tools/highlighter-helper/src/node/utils/resolveAttr.ts @@ -1,3 +1,19 @@ +/** + * Resolve attribute value from code block info string + * + * 从代码块信息字符串中解析属性值 + * + * @param info - Code block info string / 代码块信息字符串 + * @param attr - Attribute name to resolve / 要解析的属性名 + * @returns The attribute value or null if not found / 属性值，如果未找到则返回 null + * + * @example + * ```ts + * resolveAttr('js title="example.js"', 'title') // 'example.js' + * resolveAttr('js title=\'example.js\'', 'title') // 'example.js' + * resolveAttr('js', 'title') // null + * ``` + */ export const resolveAttr = (info: string, attr: string): string | null => { // try to match specified attr mark const pattern = `\\b${attr}\\s*=\\s*(?['"])(?.+?)\\k(\\s|$)` diff --git a/tools/highlighter-helper/src/node/whitespace.ts b/tools/highlighter-helper/src/node/whitespace.ts index b29a0cc856..a740a0c656 100644 --- a/tools/highlighter-helper/src/node/whitespace.ts +++ b/tools/highlighter-helper/src/node/whitespace.ts @@ -1,10 +1,42 @@ +/** + * Regular expression to match `:whitespace` directive in code block info + * + * 匹配代码块信息中 `:whitespace` 指令的正则表达式 + */ export const WHITESPACE_REGEXP = /:whitespace(?:=(all|boundary|trailing)?)?\b/ + +/** + * Regular expression to match `:no-whitespace` directive in code block info + * + * 匹配代码块信息中 `:no-whitespace` 指令的正则表达式 + */ export const NO_WHITESPACE_REGEXP = /:no-whitespace\b/ +/** + * Whitespace position types + * + * 空白符位置类型 + */ export type WhitespacePosition = 'all' | 'boundary' | 'trailing' const AVAILABLE_WHITESPACE_POSITIONS = ['all', 'boundary', 'trailing'] +/** + * Resolve whitespace position from code block info and global option + * + * 从代码块信息和全局选项中解析空白符位置 + * + * @param info - Code block info string / 代码块信息字符串 + * @param globalOption - Global whitespace option / 全局空白符选项 + * @returns Resolved whitespace position or false if disabled / 解析的空白符位置，如果禁用则返回 false + * + * @example + * ```ts + * resolveWhitespacePosition('js :whitespace=all', 'boundary') // 'all' + * resolveWhitespacePosition('js :no-whitespace', 'boundary') // false + * resolveWhitespacePosition('js', 'boundary') // 'boundary' + * ``` + */ export const resolveWhitespacePosition = ( info: string, globalOption: WhitespacePosition | true,