From d79d566442a7ee40727b4d34089d6a2abdf2181a Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Wed, 4 Jun 2025 13:49:27 +0800 Subject: [PATCH] refactor(plugin-copyright): improve docs and add jsdoc --- docs/plugins/features/copyright.md | 57 +++++++++--------- docs/zh/plugins/features/copyright.md | 58 +++++++++---------- .../src/node/copyrightPlugin.ts | 22 +++++++ .../plugin-copyright/src/node/locales.ts | 38 ++++++++++-- .../plugin-copyright/src/node/options.ts | 14 +++-- .../plugin-copyright/src/shared/data.ts | 26 +++++++++ .../src/shared/frontmatter.ts | 6 +- .../plugin-copyright/src/shared/locales.ts | 18 +++--- .../plugin-copyright/src/shared/options.ts | 4 +- 9 files changed, 161 insertions(+), 82 deletions(-) diff --git a/docs/plugins/features/copyright.md b/docs/plugins/features/copyright.md index 839a572e7d..3510abcc87 100644 --- a/docs/plugins/features/copyright.md +++ b/docs/plugins/features/copyright.md @@ -33,7 +33,7 @@ This plugin **is disabled globally by default**, you can: - Manually enable it by setting `copy: true` in page frontmatter - Set `global: true` in plugin options to enable it globally, and set `copy: false` in page frontmatter to disable it. -To avoid disturbing visitors, copyright information will be appended only when the copied content length is greater than 100. Set `triggerLength` in plugin options if you want to change this threshold, or via `copy.triggerLength` in page frontmatter. +To avoid disturbing visitors, copyright information will be appended only when the copied content length is greater than 100. Set `triggerLength` in plugin options if you want to change this threshold, or set `copy.triggerLength` in page frontmatter. You can set default author and license information via `author` and `license` in plugin options. @@ -43,22 +43,22 @@ The plugin will generate copyright information from author, license, and page li ### Disable Copy and Selection -If you want to prevent users copying long content, you can set `maxLength` in plugin options to customize this limit, or via `copy.maxLength` in page frontmatter. +If you want to prevent users copying long content, you can set `maxLength` in plugin options to customize this limit, or set `copy.maxLength` in page frontmatter. -- If you don't want users to copy your entire site or specific page text, you can set `disableCopy` in plugin options or `copy.disableCopy` in page frontmatter, the latter has higher priority. -- If you don't want users to select your entire site or specific page text, you can set `disableSelection` in plugin options or `copy.disableSelection` in page frontmatter. This option has higher priority. +- If you don't want users to copy your entire site or specific page text, you can set `disableCopy` in plugin options or `copy.disableCopy` in page frontmatter. The latter has higher priority. +- If you don't want users to select your entire site or specific page text, you can set `disableSelection` in plugin options or `copy.disableSelection` in page frontmatter. The latter has higher priority. ## Options ### author - Type: `string` -- Details: Default author Information +- Details: Default author information ### license - Type: `string` -- Details: Default license Information +- Details: Default license information ### authorGetter @@ -75,23 +75,27 @@ If you want to prevent users copying long content, you can set `maxLength` in pl - Type: `(page: Page) => string | null` - Details: Copyright getter -### triggerLength +### canonical -- Type: `number` -- Default: `100` -- Details: Min content length triggering copyright append +- Type: `string` +- Details: Canonical deploy location -### maxLength + ::: tip Example -- Type: `number` -- Default: `0` -- Details: Max content length which allows to copy, `0` means no limit. + If you are deploying same content under `https://myblog.com` and `https://blog.com/username/`, you may want to prefer one site as reference link. + + - If you prefer the first one, you should set `canonical` to `https://myblog.com` + - If you prefer the second one, you should set `canonical` to `https://blog.com/username/` + + So copyright message triggered on another site also points to your preferred site. + + ::: ### global - Type: `boolean` - Default: `false` -- Details: Whether enable globally. +- Details: Whether enable globally ### disableCopy @@ -105,21 +109,17 @@ If you want to prevent users copying long content, you can set `maxLength` in pl - Default: `false` - Details: Disable selection -### canonical - -- Type: `string` -- Details: Canonical deploy location. - -::: tip Example - -If you are deploying same content under `https://myblog.com` and `https://blog.com/username/`, you may want to prefer one site as reference link. +### triggerLength -- If you prefer the first one, you should set `canonical` to `https://myblog.com` -- If you prefer the second one, you should set `canonical` to `https://blog.com/username/` +- Type: `number` +- Default: `100` +- Details: Min content length triggering copyright append -So copyright message triggered on another site also points to your preferred site. +### maxLength -::: +- Type: `number` +- Default: `0` +- Details: Max content length which allows to copy, `0` means no limit ### locales @@ -208,6 +208,7 @@ So copyright message triggered on another site also points to your preferred sit - **Turkish** (tr-TR) - **Korean** (ko-KR) - **Finnish** (fi-FI) +- **Hungarian** (hu-HU) - **Indonesian** (id-ID) - **Dutch** (nl-NL) @@ -225,7 +226,7 @@ So copyright message triggered on another site also points to your preferred sit - Type: `number` - Default: `0` -- Details: Max content length which allows to copy, `0` means no limit. +- Details: Max content length which allows to copy, `0` means no limit ### copy.disableCopy diff --git a/docs/zh/plugins/features/copyright.md b/docs/zh/plugins/features/copyright.md index d63d917b64..e28658aac5 100644 --- a/docs/zh/plugins/features/copyright.md +++ b/docs/zh/plugins/features/copyright.md @@ -43,10 +43,10 @@ export default { ### 禁用复制和选择 -如果你希望禁止用户复制较长内容，你可以在插件选项中设置 `maxLength` 控制这个临界值，或在页面 frontmatter 单独设置 `copy.maxLength`。 +如果你希望禁止用户复制较长内容，你可以在插件选项中设置 `maxLength` 控制这个临界值，或在页面 frontmatter 中设置 `copy.maxLength`。 -- 如果你不希望用户复制你的整个站点或特定页面文字，你可以在插件选项中设置 `disableCopy` 或在页面 frontmatter 中设置 `copy.disableCopy` 来禁用复制，后者具有更高优先级。 -- 如果你不希望用户选择你的整个站点或特定页面文字，你可以在插件选项中设置 `disableSelection` 或在页面 frontmatter 中设置 `copy.disableSelection` 来禁用文字选择。此选项具有更高优先级 +- 如果你不希望用户复制你的整个站点或特定页面文字，你可以在插件选项中设置 `disableCopy` 或在页面 frontmatter 中设置 `copy.disableCopy` 来禁用复制。后者具有更高优先级。 +- 如果你不希望用户选择你的整个站点或特定页面文字，你可以在插件选项中设置 `disableSelection` 或在页面 frontmatter 中设置 `copy.disableSelection` 来禁用文字选择。后者具有更高优先级。 ## 选项 @@ -73,19 +73,23 @@ export default { ### copyrightGetter - 类型：`(page: Page) => string | null` -- 详情：协议信息获取器 +- 详情：版权信息获取器 -### triggerLength +### canonical -- 类型：`number` -- 默认值：`100` -- 详情：触发附加版权的最小内容长度 +- 类型：`string` +- 详情：首选部署位置 -### maxLength + ::: tip 例子 -- 类型：`number` -- 默认值：`0` -- 详情：允许复制的最大内容长度，`0` 意味着无限制。 + 如果你在 `https://myblog.com` 和 `https://blog.com/username/` 下部署相同的内容，你可能希望选择一个站点作为首选链接。 + + - 如果你倾向于使用第一个，你应该将 `canonical` 设置为 `https://myblog.com` + - 如果你倾向于使用第二个，你应该将 `canonical` 设置为 `https://blog.com/username/` + + 这样，在另一个站点触发的版权信息也会指向你的首选站点。 + + ::: ### global @@ -105,23 +109,17 @@ export default { - 默认值：`false` - 详情：禁用选择 -### canonical - -- 类型：`string` -- 详情： - - 首选部署位置。 - -::: tip 例子 - -如果你在 `https://myblog.com` 和 `https://blog.com/username/` 下部署相同的内容，你可能希望选择一个站点作为首选链接。 +### triggerLength -- 如果你倾向于使用第一个，你应该将 `canonical` 设置为 `https://myblog.com` -- 如果你倾向于使用第二个，你应该将 `canonical` 设置为 `https://blog.com/username/` +- 类型：`number` +- 默认值：`100` +- 详情：触发附加版权的最小内容长度 -这样，在另一个站点触发的版权信息也会指向你的首选站点。 +### maxLength -::: +- 类型：`number` +- 默认值：`0` +- 详情：允许复制的最大内容长度，`0` 意味着无限制 ### locales @@ -204,11 +202,12 @@ export default { - **波兰语** (pl-PL) - **法语** (fr-FR) - **西班牙语** (es-ES) -- **斯洛伐克** (sk-SK) +- **斯洛伐克语** (sk-SK) - **日语** (ja-JP) - **土耳其语** (tr-TR) - **韩语** (ko-KR) - **芬兰语** (fi-FI) +- **匈牙利语** (hu-HU) - **印尼语** (id-ID) - **荷兰语** (nl-NL) @@ -220,14 +219,13 @@ export default { - 类型：`number` - 默认值：`100` -- 详情： 触发附加版权的最小内容长度 +- 详情：触发附加版权的最小内容长度 ### copy.maxLength - 类型：`number` - 默认值：`0` -- 详情： - 允许复制的最大内容长度，`0` 意味着无限制。 +- 详情：允许复制的最大内容长度，`0` 意味着无限制 ### copy.disableCopy diff --git a/plugins/features/plugin-copyright/src/node/copyrightPlugin.ts b/plugins/features/plugin-copyright/src/node/copyrightPlugin.ts index eb0e90ba09..331681c810 100644 --- a/plugins/features/plugin-copyright/src/node/copyrightPlugin.ts +++ b/plugins/features/plugin-copyright/src/node/copyrightPlugin.ts @@ -18,6 +18,28 @@ export const logger = new Logger(PLUGIN_NAME) const __dirname = import.meta.dirname || getDirname(import.meta.url) +/** + * Copyright plugin + * + * 版权插件 + * + * @param options - Plugin options / 插件选项 + * + * @example + * ```ts + * import { copyrightPlugin } from '@vuepress/plugin-copyright' + * + * export default { + * plugins: [ + * copyrightPlugin({ + * author: 'Your Name', + * license: 'MIT', + * global: true, + * }), + * ], + * } + * ``` + */ export const copyrightPlugin = (options: CopyrightPluginOptions = {}): PluginFunction => (app) => { diff --git a/plugins/features/plugin-copyright/src/node/locales.ts b/plugins/features/plugin-copyright/src/node/locales.ts index 5e3c08503f..4387cd80f3 100644 --- a/plugins/features/plugin-copyright/src/node/locales.ts +++ b/plugins/features/plugin-copyright/src/node/locales.ts @@ -2,7 +2,9 @@ import type { DefaultLocaleInfo } from '@vuepress/helper' import type { CopyrightPluginLocaleData } from '../shared/index.js' /** - * Default locale info for `@vuepress/plugin-copyright` + * Default locale info for copyright plugin + * + * 版权插件的默认多语言信息 */ export const copyrightLocaleInfo: DefaultLocaleInfo = [ @@ -38,6 +40,30 @@ export const copyrightLocaleInfo: DefaultLocaleInfo = link: ':link', }, ], + [ + ['uk', 'uk-UA'], + { + author: 'Авторські права :author', + license: 'Ліцензія :license', + link: ':link', + }, + ], + [ + ['vi', 'vi-VN'], + { + author: 'Bản quyền thuộc về :author', + license: 'Cấp phép theo :license', + link: ':link', + }, + ], + [ + ['pt-BR'], + { + author: 'Direitos autorais de :author', + license: 'Licenciado sob :license', + link: ':link', + }, + ], [ ['pl', 'pl-PL'], { @@ -74,7 +100,7 @@ export const copyrightLocaleInfo: DefaultLocaleInfo = ['ja', 'ja-JP'], { author: '著作権者 :author', - license: ':licenseプロトコルに基づく', + license: ':license ライセンスに基づく', link: ':link', }, ], @@ -87,10 +113,10 @@ export const copyrightLocaleInfo: DefaultLocaleInfo = }, ], [ - ['ko', 'ko-KO'], + ['ko', 'ko-KR'], { author: '저작권자 :author', - license: ':license 프로토콜에 따라', + license: ':license 라이선스에 따라', link: ':link', }, ], @@ -114,7 +140,7 @@ export const copyrightLocaleInfo: DefaultLocaleInfo = ['hu', 'hu-HU'], { author: 'Szerzői jog :author', - license: 'Licensz: :license', + license: 'Licenc: :license', link: ':link', }, ], @@ -122,7 +148,7 @@ export const copyrightLocaleInfo: DefaultLocaleInfo = ['id', 'id-ID'], { author: 'Hak cipta oleh :author', - license: 'Dibawah Lisensi :license', + license: 'Di bawah lisensi :license', link: ':link', }, ], diff --git a/plugins/features/plugin-copyright/src/node/options.ts b/plugins/features/plugin-copyright/src/node/options.ts index ba21e9ab8b..48321f954f 100644 --- a/plugins/features/plugin-copyright/src/node/options.ts +++ b/plugins/features/plugin-copyright/src/node/options.ts @@ -7,9 +7,11 @@ import type { export interface CopyrightPluginOptions extends CopyrightPluginSharedOptions { /** - * Author Getter + * Author getter * * 作者获取器 + * + * @param page - Page object / 页面对象 */ authorGetter?: < ExtraPageData extends Record = Record, @@ -26,6 +28,8 @@ export interface CopyrightPluginOptions extends CopyrightPluginSharedOptions { * License getter * * 协议信息获取器 + * + * @param page - Page object / 页面对象 */ licenseGetter?: < ExtraPageData extends Record = Record, @@ -39,9 +43,11 @@ export interface CopyrightPluginOptions extends CopyrightPluginSharedOptions { ) => string | null /** - * Copyright Getter + * Copyright getter + * + * 版权信息获取器 * - * 协议获取器 + * @param page - Page object / 页面对象 */ copyrightGetter?: < ExtraPageData extends Record = Record, @@ -57,7 +63,7 @@ export interface CopyrightPluginOptions extends CopyrightPluginSharedOptions { /** * Locales config for copyright * - * 复制版权的多语言配置 + * 版权插件的多语言配置 */ locales?: LocaleConfig } diff --git a/plugins/features/plugin-copyright/src/shared/data.ts b/plugins/features/plugin-copyright/src/shared/data.ts index 64da437883..a49f1ce203 100644 --- a/plugins/features/plugin-copyright/src/shared/data.ts +++ b/plugins/features/plugin-copyright/src/shared/data.ts @@ -1,8 +1,34 @@ +/** + * Copyright information data + * + * 版权信息数据 + */ export interface CopyrightInfoData { + /** + * Author information + * + * 作者信息 + */ author?: string + + /** + * License information + * + * 协议信息 + */ license?: string } +/** + * Copyright plugin page data + * + * 版权插件页面数据 + */ export interface CopyrightPluginPageData extends Record { + /** + * Copyright information + * + * 版权信息 + */ copyright?: CopyrightInfoData | string } diff --git a/plugins/features/plugin-copyright/src/shared/frontmatter.ts b/plugins/features/plugin-copyright/src/shared/frontmatter.ts index 37acd7e0c2..0bac1bde9f 100644 --- a/plugins/features/plugin-copyright/src/shared/frontmatter.ts +++ b/plugins/features/plugin-copyright/src/shared/frontmatter.ts @@ -5,9 +5,9 @@ export interface CopyrightPluginFrontmatter extends PageFrontmatter { | boolean | { /** - * Min words triggering copyright append + * Min length triggering copyright append * - * 触发附加版权的最小字数 + * 触发附加版权的最小长度 * * @default 100 */ @@ -18,7 +18,7 @@ export interface CopyrightPluginFrontmatter extends PageFrontmatter { * * @description 0 means unlimited * - * 允许复制的最大字数 + * 允许复制的最大长度 * * @description 0 表示无限制 * diff --git a/plugins/features/plugin-copyright/src/shared/locales.ts b/plugins/features/plugin-copyright/src/shared/locales.ts index 99ee3107b3..9a6bcf0f56 100644 --- a/plugins/features/plugin-copyright/src/shared/locales.ts +++ b/plugins/features/plugin-copyright/src/shared/locales.ts @@ -2,33 +2,33 @@ export interface CopyrightPluginLocaleData { /** * Author text * - * @description `:author` will be replaced by author - * * 作者文字 * - * @description `:author` 将会被作者替换 + * @description `:author` will be replaced by author + * + * `:author` 将会被作者替换 */ author: string /** * License text * - * @description `:license` will be replaced by current license - * * 协议文字 * - * @description `:license` 会被当前协议替换 + * @description `:license` will be replaced by current license + * + * `:license` 会被当前协议替换 */ license: string /** * Link text * - * @description `:link` will be replaced by current page link - * * 链接文字 * - * @description `:link` 会替换为当前页面链接 + * @description `:link` will be replaced by current page link + * + * `:link` 会替换为当前页面链接 */ link: string } diff --git a/plugins/features/plugin-copyright/src/shared/options.ts b/plugins/features/plugin-copyright/src/shared/options.ts index 51081da7dc..397ca25c35 100644 --- a/plugins/features/plugin-copyright/src/shared/options.ts +++ b/plugins/features/plugin-copyright/src/shared/options.ts @@ -1,13 +1,13 @@ export interface CopyrightPluginSharedOptions { /** - * Default Author Information + * Default author information * * 默认作者信息 */ author?: string /** - * Default License Information + * Default license information * * 默认协议信息 */