Merge branch 'main' into prettier

vuepress · Feb 1, 2024 · 02b0d67 · 02b0d67
2 parents 673729c + 8402530
commit 02b0d67
Show file tree

Hide file tree

Showing 31 changed files with 911 additions and 0 deletions.
diff --git a/docs/.vuepress/configs/navbar/en.ts b/docs/.vuepress/configs/navbar/en.ts
@@ -18,6 +18,7 @@ export const navbarEn: NavbarConfig = [
         children: [
           '/plugins/back-to-top',
           '/plugins/container',
+          '/plugins/copy-code',
           '/plugins/external-link-icon',
           '/plugins/google-analytics',
           '/plugins/medium-zoom',

diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts
@@ -18,6 +18,7 @@ export const navbarZh: NavbarConfig = [
         children: [
           '/zh/plugins/back-to-top',
           '/zh/plugins/container',
+          '/zh/plugins/copy-code',
           '/zh/plugins/external-link-icon',
           '/zh/plugins/google-analytics',
           '/zh/plugins/medium-zoom',

diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts
@@ -7,6 +7,7 @@ export const sidebarEn: SidebarConfig = {
       children: [
         '/plugins/back-to-top',
         '/plugins/container',
+        '/plugins/copy-code',
         '/plugins/external-link-icon',
         '/plugins/google-analytics',
         '/plugins/medium-zoom',

diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts
@@ -7,6 +7,7 @@ export const sidebarZh: SidebarConfig = {
       children: [
         '/zh/plugins/back-to-top',
         '/zh/plugins/container',
+        '/zh/plugins/copy-code',
         '/zh/plugins/external-link-icon',
         '/zh/plugins/google-analytics',
         '/zh/plugins/medium-zoom',

diff --git a/docs/package.json b/docs/package.json
@@ -12,6 +12,7 @@
     "@vuepress/bundler-vite": "2.0.0-rc.2",
     "@vuepress/bundler-webpack": "2.0.0-rc.2",
     "@vuepress/plugin-back-to-top": "workspace:*",
+    "@vuepress/plugin-copy-code": "workspace:*",
     "@vuepress/plugin-docsearch": "workspace:*",
     "@vuepress/plugin-external-link-icon": "workspace:*",
     "@vuepress/plugin-google-analytics": "workspace:*",

diff --git a/docs/plugins/copy-code.md b/docs/plugins/copy-code.md
@@ -0,0 +1,153 @@
+# copy-code
+
+<NpmBadge package="@vuepress/plugin-copy-code" />
+
+This plugin will automatically add a copy button to the top right corner of each code block on PC devices.
+
+The default selector matches `@vuepress/theme-default`, so you might need to change it when integrating your own theme.
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-copy-code@next
+```
+
+```ts
+import { copyCodePlugin } from '@vuepress/plugin-copy-code'
+
+export default {
+  plugins: [
+    copyCodePlugin({
+      // options
+    }),
+  ],
+}
+```
+
+## Options
+
+### selector
+
+- Type: `string | string[]`
+- Default: `'.theme-default-content div[class*="language-"] pre'`
+- Details:
+
+  Code block selector
+
+### showInMobile
+
+- Type: `boolean`
+- Default: `false`
+- Details:
+
+  Whether to display copy button on the mobile device
+
+### duration
+
+- Type: `number`
+- Default: `2000`
+- Details:
+
+  Hint display time, setting it to `0` will disable the hint.
+
+### delay
+
+- Type: `number`
+- Default: `800`
+- Details:
+
+  The delay of registering copy code buttons, in ms.
+
+  If the theme you are using has a switching animation, it is recommended to configure this option to `Switch animation duration + 200`.
+
+### locales
+
+- Type: `CopyCodeLocaleConfig`
+
+  ```ts
+  interface CopyCodeLocaleData {
+    /**
+     * Copy text
+     */
+    copy: string
+
+    /**
+     * Copied text
+     */
+    copied: string
+  }
+
+  interface CopyCodeLocaleConfig {
+    [localePath: string]: CopyCodeLocaleData
+  }
+  ```
+
+- Required: No
+
+- Details:
+
+  Locales config for copy code plugin.
+
+- Example:
+
+  ```ts
+  import { copyCodePlugin } from "vuepress-plugin-copy-code2";
+
+  export default {
+    locales: {
+      "/": {
+        // this is a supported language
+        lang: "en-US",
+      },
+      "/xx/": {
+        // the plugin does not support this language
+        lang: "mm-NN",
+      },
+    },
+
+    plugins: [
+      copyCodePlugin({
+        locales: {
+          "/": {
+            // Override copy button label text
+            copy: "Copy Codes from code block",
+          },
+
+          "/xx/": {
+            // Complete locale config for `mm-NN` language here
+          },
+        },
+      }),
+    ],
+  };
+  ```
+
+::: details Built-in Supported Languages
+
+- **Simplified Chinese** (zh-CN)
+- **Traditional Chinese** (zh-TW)
+- **English (United States)** (en-US)
+- **German** (de-DE)
+- **German (Australia)** (de-AT)
+- **Russian** (ru-RU)
+- **Ukrainian** (uk-UA)
+- **Vietnamese** (vi-VN)
+- **Portuguese (Brazil)** (pt-BR)
+- **Polish** (pl-PL)
+- **French** (fr-FR)
+- **Spanish** (es-ES)
+- **Slovak** (sk-SK)
+- **Japanese** (ja-JP)
+- **Turkish** (tr-TR)
+- **Korean** (ko-KR)
+- **Finnish** (fi-FI)
+- **Indonesian** (id-ID)
+- **Dutch** (nl-NL)
+
+:::
+
+## Styles
+
+You can customize the icon of the *copy button* via CSS variables:
+
+@[code css](@vuepress/plugin-copy-code/src/client/styles/vars.css)
diff --git a/docs/themes/default/config.md b/docs/themes/default/config.md
@@ -711,6 +711,16 @@ The generated link will look like `'https://gitlab.com/owner/name/-/edit/master/
 
   Enable [@vuepress/plugin-external-link-icon](../../plugins/external-link-icon.md) or not.
 
+### themePlugins.copyCode
+
+- Type: `boolean`
+
+- Default: `true`
+
+- Details:
+
+  Enable [@vuepress/plugin-copy-code](../../plugins/copy-code.md) or not.
+
 ### themePlugins.git
 
 - Type: `boolean`

diff --git a/docs/zh/plugins/copy-code.md b/docs/zh/plugins/copy-code.md
@@ -0,0 +1,154 @@
+# copy-code
+
+<NpmBadge package="@vuepress/plugin-copy-code" />
+
+此插件会自动在 PC 设备上为每个代码块右上角添加复制按钮。
+
+默认选择器匹配 `@vuepress/theme-default`，所以在你自己的主题中集成时可能需要调整它。
+
+## 使用
+
+```bash
+npm i -D @vuepress/plugin-copy-code@next
+```
+
+```ts
+import { copyCodePlugin } from '@vuepress/plugin-copy-code'
+
+export default {
+  plugins: [
+    copyCodePlugin({
+      // options
+    }),
+  ],
+}
+```
+
+## 使用方法
+
+### selector
+
+- 类型: `string | string[]`
+- 默认值: `'.theme-default-content div[class*="language-"] pre'`
+- 详情:
+
+  代码块选择器
+
+### showInMobile
+
+- 类型: `boolean`
+- 默认值: `false`
+- 详情:
+
+  是否展示在移动端
+
+### duration
+
+- 类型: `number`
+- 默认值: `2000`
+- 详情:
+
+  提示消息显示时间，设置为 `0` 会禁用提示。
+
+### delay
+
+- 类型: `number`
+- 默认值: `800`
+- 详情:
+
+  注册复制按钮的延时，单位 ms。
+
+  如果你使用的主题有切换动画，建议配置此选项为 `切换动画时长 + 200`
+
+### locales
+
+- 类型: `CopyCodeLocaleConfig`
+
+  ```ts
+  interface CopyCodeLocaleData {
+    /**
+     * 复制文字
+     */
+    copy: string;
+
+    /**
+     * 已复制文字
+     */
+    copied: string;
+  }
+
+  interface CopyCodeLocaleConfig {
+    [localePath: string]: CopyCodeLocaleData;
+  }
+  ```
+
+- 必填: 否
+- 详情:
+
+  复制按钮插件的国际化配置。
+
+- 示例：
+
+  ```ts
+  import { copyCodePlugin } from "vuepress-plugin-copy-code2";
+
+  export default {
+    locales: {
+      "/": {
+        // 这是一个支持的语言
+        lang: "zh-CN",
+      },
+      "/xx/": {
+        // 这是一个没有收到插件支持的语言
+        lang: "mm-NN",
+      },
+    },
+
+    plugins: [
+      copyCodePlugin({
+        locales: {
+          "/": {
+            // 覆盖复制按钮标签文字
+            copy: "复制此段代码",
+          },
+
+          "/xx/": {
+            // 在这里完整设置 `mm-NN` 的多语言配置
+          },
+        },
+      }),
+    ],
+  };
+  ```
+
+::: details 内置支持语言
+
+- **简体中文** (zh-CN)
+- **繁体中文** (zh-TW)
+- **英文(美国)** (en-US)
+- **德语** (de-DE)
+- **德语(澳大利亚)** (de-AT)
+- **俄语** (ru-RU)
+- **乌克兰语** (uk-UA)
+- **越南语** (vi-VN)
+- **葡萄牙语(巴西)** (pt-BR)
+- **波兰语** (pl-PL)
+- **法语** (fr-FR)
+- **西班牙语** (es-ES)
+- **斯洛伐克** (sk-SK)
+- **日语** (ja-JP)
+- **土耳其语** (tr-TR)
+- **韩语** (ko-KR)
+- **芬兰语** (fi-FI)
+- **印尼语** (id-ID)
+- **荷兰语** (nl-NL)
+
+:::
+
+
+## 样式
+
+你可以通过 CSS 变量来自定义*复制按钮*的样式：
+
+
+@[code css](@vuepress/plugin-copy-code/src/client/styles/vars.css)
diff --git a/docs/zh/themes/default/config.md b/docs/zh/themes/default/config.md
@@ -701,6 +701,16 @@ export default {
 - 参考：
   - [默认主题 > Markdown > 自定义容器](./markdown.md#自定义容器)
 
+### themePlugins.copyCode
+
+- 类型： `boolean`
+
+- 默认值： `true`
+
+- 详情：
+
+  是否启用 [@vuepress/plugin-copy-code](../../plugins/copy-code.md) 。
+
 ### themePlugins.externalLinkIcon
 
 - 类型： `boolean`

diff --git a/e2e/tests/plugin-copy-code/copy-code.cy.ts b/e2e/tests/plugin-copy-code/copy-code.cy.ts
@@ -0,0 +1,12 @@
+describe('copy-code', () => {
+  it('have copy code button', () => {
+    cy.visit('/markdown.html')
+      .get('.copy-code-button')
+      .then((el) => {
+        expect(el.length).to.be.greaterThan(0)
+
+        cy.wrap(el).click({ multiple: true })
+        cy.wrap(el).should('have.class', 'copied')
+      })
+  })
+})