From 5cfa771d28b527596c7ae00fd4617dd21a78c2c0 Mon Sep 17 00:00:00 2001
From: "Mr.Hope" <mister-hope@outlook.com>
Date: Sun, 14 Jul 2024 22:29:58 +0800
Subject: [PATCH] feat: update markdown code description

---
 docs/guide/markdown.md      |  10 ++--
 docs/guide/migration.md     |   9 ++-
 docs/reference/config.md    | 110 +++++++++---------------------------
 docs/zh/guide/markdown.md   |   8 +--
 docs/zh/guide/migration.md  |   9 ++-
 docs/zh/reference/config.md | 110 +++++++++---------------------------
 6 files changed, 73 insertions(+), 183 deletions(-)

diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index 30cb6728..06204786 100644
--- a/docs/guide/markdown.md
+++ b/docs/guide/markdown.md
@@ -158,7 +158,7 @@ Following code blocks extensions are implemented during markdown parsing in Node
 
 #### Code Title
 
-You can specify the title of the code block by adding a `title` key-value mark in your fenced code blocks.
+You can specify the title of the code block by adding a `title` key-value mark in your fenced code blocks. Note: This requires theme support.
 
 **Input**
 
@@ -196,7 +196,7 @@ It can be used in combination with the other marks below. Please leave a space b
 
 #### Line Highlighting
 
-You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks:
+You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks. Note: This requires highlighter plugin and theme support.
 
 **Input**
 
@@ -244,9 +244,9 @@ Config reference: [markdown.code.highlightLines](../reference/config.md#markdown
 
 #### Line Numbers
 
-You must have noticed that the number of lines is displayed on the left side of code blocks. This is enabled by default and you can disable it in config.
+You must have noticed that the number of lines is displayed on the left side of code blocks.
 
-You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
+You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config. Note: This requires highlighter plugin and theme support.
 
 **Input**
 
@@ -346,7 +346,7 @@ const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
 ::: tip
 This v-pre extension is supported by our built-in plugin.
 
-Config reference: [markdown.code.vPre.block](../reference/config.md#markdown-code-vpre-block)
+Config reference: [markdown.vPre.block](../reference/config.md#markdown-vpre-block)
 :::
 
 ### Import Code Blocks
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
index 69150d28..876320af 100644
--- a/docs/guide/migration.md
+++ b/docs/guide/migration.md
@@ -145,9 +145,9 @@ Renamed to `pagePatterns`
 
 #### markdown.lineNumbers
 
-Moved to [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers).
+Removed.
 
-Default value is changed from `false` to `true`.
+The same feature is implemented in [@vuepress/plugin-prismjs][prismjs] and [@vuepress/plugin-shiki][shiki].
 
 #### markdown.pageSuffix
 
@@ -414,7 +414,7 @@ Some major breaking changes:
   - Always provide a valid js entry file, and do not use `"main": "layouts/Layout.vue"` as the theme entry anymore.
 - `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/plugins/theme-data.html) plugin and its `useThemeData` composition API.
 - Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, [@vuepress/plugin-palette](https://ecosystem.vuejs.press/plugins/palette.html) may help.
-- Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/plugins/prismjs.html) or [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/plugins/shiki.html), or implement syntax highlighting in your own way.
+- Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs][prismjs] or [@vuepress/plugin-shiki][shiki], or implement syntax highlighting in your own way.
 - For scalability concerns, `this.$site.pages` is not available any more. See [Advanced > Cookbook > Resolving Routes](../advanced/cookbook/resolving-routes.md) for how to retrieve pages data in v2.
 
 For more detailed guide about how to write a theme in v2, see [Advanced > Writing a Theme](../advanced/theme.md).
@@ -438,3 +438,6 @@ You can still inherit a parent theme with `extends: parentTheme()`, which will e
 You can refer to [Default Theme > Extending](https://ecosystem.vuejs.press/themes/default/extending.html) for how to extend default theme.
 
 The `@theme` and `@parent-theme` aliases are removed by default, but you can still make a extendable theme with similar approach, see [Advanced > Cookbook > Making a Theme Extendable](../advanced/cookbook/making-a-theme-extendable.md).
+
+[prismjs]: https://ecosystem.vuejs.press/plugins/prismjs.html
+[shiki]: https://ecosystem.vuejs.press/plugins/shiki.html
diff --git a/docs/reference/config.md b/docs/reference/config.md
index fdcff7df..8addf8f9 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -400,90 +400,6 @@ const defaultOptions = {
 You should not configure it unless you understand what it is for.
 :::
 
-### markdown.code
-
-- Type: `CodePluginOptions | false`
-
-- Details:
-
-  Options for VuePress built-in markdown-it code plugin.
-
-  Set to `false` to disable this plugin.
-
-- Also see:
-  - [Guide > Markdown > Syntax Extensions > Code Blocks](../guide/markdown.md#code-blocks)
-
-#### markdown.code.highlightLines
-
-- Type: `boolean`
-
-- Default: `true`
-
-- Details:
-
-  Enable code line highlighting or not.
-
-- Also see:
-  - [Guide > Markdown > Syntax Extensions > Code Blocks > Line Highlighting](../guide/markdown.md#line-highlighting)
-
-#### markdown.code.lineNumbers
-
-- Type: `boolean | number`
-
-- Default: `true`
-
-- Details:
-
-  Configure code line numbers.
-
-  - A `boolean` value is to enable line numbers or not.
-  - A `number` value is the minimum number of lines to enable line numbers. For example, if you set it to `4`, line numbers will only be enabled when your code block has at least 4 lines of code.
-
-- Also see:
-  - [Guide > Markdown > Syntax Extensions > Code Blocks > Line Numbers](../guide/markdown.md#line-numbers)
-
-#### markdown.code.preWrapper
-
-- Type: `boolean`
-
-- Default: `true`
-
-- Details:
-
-  Enable the extra wrapper of the `<pre>` tag or not.
-
-  The wrapper is required by the `highlightLines` and `lineNumbers`. That means, if you disable `preWrapper`, the line highlighting and line numbers will also be disabled.
-
-::: tip
-You can disable it if you want to implement them in client side. For example, [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) or [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/).
-:::
-
-#### markdown.code.vPre.block
-
-- Type: `boolean`
-
-- Default: `true`
-
-- Details:
-
-  Add `v-pre` directive to `<pre>` tag of code block or not.
-
-- Also see:
-  - [Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre](../guide/markdown.md#wrap-with-v-pre)
-
-#### markdown.code.vPre.inline
-
-- Type: `boolean`
-
-- Default: `true`
-
-- Details:
-
-  Add `v-pre` directive to `<code>` tag of inline code or not.
-
-- Also see:
-  - [Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre](../guide/markdown.md#wrap-with-v-pre)
-
 ### markdown.component
 
 - Type: `undefined | false`
@@ -671,6 +587,32 @@ const defaultOptions = {
 - Also see:
   - [Guide > Markdown > Syntax Extensions > Table of Contents](../guide/markdown.md#table-of-contents)
 
+#### markdown.vPre.block
+
+- Type: `boolean`
+
+- Default: `true`
+
+- Details:
+
+  Add `v-pre` directive to `<pre>` tag of code block or not.
+
+- Also see:
+  - [Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre](../guide/markdown.md#wrap-with-v-pre)
+
+#### markdown.vPre.inline
+
+- Type: `boolean`
+
+- Default: `true`
+
+- Details:
+
+  Add `v-pre` directive to `<code>` tag of inline code or not.
+
+- Also see:
+  - [Guide > Markdown > Syntax Extensions > Code Blocks > Wrap with v-pre](../guide/markdown.md#wrap-with-v-pre)
+
 ## Plugin Config
 
 ### plugins
diff --git a/docs/zh/guide/markdown.md b/docs/zh/guide/markdown.md
index e16a0d04..74857e2d 100644
--- a/docs/zh/guide/markdown.md
+++ b/docs/zh/guide/markdown.md
@@ -159,7 +159,7 @@ Emoji 扩展由 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-e
 
 #### 代码标题
 
-你可以在代码块添加一个 `title` 键值对来为代码块设置标题。
+你可以在代码块添加一个 `title` 键值对来为代码块设置标题。提示：需要主题支持。
 
 **Input**
 
@@ -197,7 +197,7 @@ export default defineUserConfig({
 
 #### 行高亮
 
-你可以在代码块添加行数范围标记，来为对应代码行进行高亮：
+你可以在代码块添加行数范围标记，来为对应代码行进行高亮。提示：它需要高亮器插件和主题支持。
 
 **输入**
 
@@ -245,7 +245,7 @@ export default defineUserConfig({
 
 #### 行号
 
-你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。
+你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。提示：它需要高亮器插件和主题支持。
 
 你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置。
 
@@ -347,7 +347,7 @@ const onePlusTwoPlusThree = {{ 1 + 2 + 3 }}
 ::: tip
 v-pre 扩展是由我们的内置插件支持的。
 
-配置参考： [markdown.code.vPre.block](../reference/config.md#markdown-code-vpre-block)
+配置参考： [markdown.vPre.block](../reference/config.md#markdown-vpre-block)
 :::
 
 ### 导入代码块
diff --git a/docs/zh/guide/migration.md b/docs/zh/guide/migration.md
index fe7563b1..b78d9924 100644
--- a/docs/zh/guide/migration.md
+++ b/docs/zh/guide/migration.md
@@ -145,9 +145,9 @@ npm i -D @vuepress/theme-default@next
 
 #### markdown.lineNumbers
 
-移动至 [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers) 。
+移除。
 
-默认值从 `false` 更改为 `true` 。
+相同的功能改在 [@vuepress/plugin-prismjs][prismjs] 和 [@vuepress/plugin-shiki][shiki] 提供。
 
 #### markdown.pageSuffix
 
@@ -416,7 +416,7 @@ v1 的主题和插件和 v2 并不兼容。
   - 你始终需要提供一个合法的 JS 入口文件，不要再使用 `"main": "layouts/Layout.vue"` 作为主题入口。
 - `themeConfig` 已经从用户配置和站点数据中移除。如果你想要像 v1 一样通过 `this.$site.themeConfig` 来访问 `themeConfig` ，我们现在建议使用 [@vuepress/plugin-theme-data](https://ecosystem.vuejs.press/zh/plugins/theme-data.html) 插件和它提供的 Composition API `useThemeData` 。
 - Stylus 不再是默认的 CSS 预处理器，并且 Stylus 调色板系统不再被默认支持。如果你仍然想要使用和 v1 类似的调色板系统，可以使用 [@vuepress/plugin-palette](https://ecosystem.vuejs.press/zh/plugins/palette.html) 。
-- 由 Prism.js 提供的 Markdown 代码块的语法高亮不再被默认支持。你可以选择使用 [@vuepress/plugin-prismjs](https://ecosystem.vuejs.press/zh/plugins/prismjs.html) 或 [@vuepress/plugin-shiki](https://ecosystem.vuejs.press/zh/plugins/plugin/shiki.html) ，或者用你自己的方式实现语法高亮。
+- 由 Prism.js 提供的 Markdown 代码块的语法高亮不再被默认支持。你可以选择使用 [@vuepress/plugin-prismjs][prismjs] 或 [@vuepress/plugin-shiki][shiki] ，或者用你自己的方式实现语法高亮。
 - 考虑到可扩展性， `this.$site.pages` 不再可用。查看 [深入 > Cookbook > 解析路由](../advanced/cookbook/resolving-routes.md) 了解如何在 v2 中获取页面的数据。
 
 你可以参考 [深入 > 开发主题](../advanced/theme.md) 来了解如何开发一个 v2 主题。
@@ -440,3 +440,6 @@ v1 的主题和插件和 v2 并不兼容。
 你可以参考 [默认主题 > 继承](https://ecosystem.vuejs.press/zh/themes/default/extending.html) 来了解如何继承默认主题。
 
 `@theme` 和 `@parent-theme` 别名默认被移除了，但你仍然可以使用类似的方式来开发一个可继承的主题，参考 [深入 > Cookbook > 开发一个可继承的主题](../advanced/cookbook/making-a-theme-extendable.md) 。
+
+[prismjs]: https://ecosystem.vuejs.press/zh/plugins/prismjs.html
+[shiki]: https://ecosystem.vuejs.press/zh/plugins/shiki.html
diff --git a/docs/zh/reference/config.md b/docs/zh/reference/config.md
index 098a8fe9..058ba119 100644
--- a/docs/zh/reference/config.md
+++ b/docs/zh/reference/config.md
@@ -399,90 +399,6 @@ const defaultOptions = {
 除非你了解它的用途，否则你不应该设置该配置项。
 :::
 
-### markdown.code
-
-- 类型： `CodePluginOptions | false`
-
-- 详情：
-
-  VuePress 内置的 markdown-it code 插件的配置项。
-
-  设置为 `false` 可以禁用该插件。
-
-- 参考：
-  - [指南 > Markdown > 语法扩展 > 代码块](../guide/markdown.md#代码块)
-
-#### markdown.code.highlightLines
-
-- 类型： `boolean`
-
-- 默认值： `true`
-
-- 详情：
-
-  是否启用代码块行高亮。
-
-- 参考：
-  - [指南 > Markdown > 语法扩展 > 代码块 > 行高亮](../guide/markdown.md#行高亮)
-
-#### markdown.code.lineNumbers
-
-- 类型： `boolean | number`
-
-- 默认值： `true`
-
-- 详情：
-
-  配置代码块行号。
-
-  - 布尔值 `boolean` 代表是否启用代码块行号。
-  - 数字 `number` 代表显示行号所需的最少行数。例如，如果你将它设置为 `4` ，那么只有在你的代码块包含至少 4 行代码时才会启用行号。
-
-- 参考：
-  - [指南 > Markdown > 语法扩展 > 代码块 > 行号](../guide/markdown.md#行号)
-
-#### markdown.code.preWrapper
-
-- 类型： `boolean`
-
-- 默认值： `true`
-
-- 详情：
-
-  是否在 `<pre>` 标签外额外包裹一层。
-
-  `highlightLines` 和 `lineNumbers` 依赖于这个额外的包裹层。这换句话说，如果你禁用了 `preWrapper` ，那么行高亮和行号也会被同时禁用。
-
-::: tip
-如果你想要在客户端来实现这些功能时，可以禁用该配置项。比如使用 [Prismjs Line Highlight](https://prismjs.com/plugins/line-highlight/) 或者 [Prismjs Line Numbers](https://prismjs.com/plugins/line-numbers/)。
-:::
-
-#### markdown.code.vPre.block
-
-- 类型： `boolean`
-
-- 默认值： `true`
-
-- 详情：
-
-  是否在代码块的 `<pre>` 标签上添加 `v-pre` 指令。
-
-- 参考：
-  - [指南 > Markdown > 语法扩展 > 代码块 > 添加 v-pre](../guide/markdown.md#添加-v-pre)
-
-#### markdown.code.vPre.inline
-
-- 类型： `boolean`
-
-- 默认值： `true`
-
-- 详情：
-
-  是否在行内代码的 `<code>` 标签上添加 `v-pre` 指令。
-
-- 参考：
-  - [指南 > Markdown > 语法扩展 > 代码块 > 添加 v-pre](../guide/markdown.md#添加-v-pre)
-
 ### markdown.component
 
 - 类型： `undefined | false`
@@ -670,6 +586,32 @@ const defaultOptions = {
 - 参考：
   - [指南 > Markdown > 语法扩展 > 目录](../guide/markdown.md#目录)
 
+#### markdown.vPre.block
+
+- 类型： `boolean`
+
+- 默认值： `true`
+
+- 详情：
+
+  是否在代码块的 `<pre>` 标签上添加 `v-pre` 指令。
+
+- 参考：
+  - [指南 > Markdown > 语法扩展 > 代码块 > 添加 v-pre](../guide/markdown.md#添加-v-pre)
+
+#### markdown.vPre.inline
+
+- 类型： `boolean`
+
+- 默认值： `true`
+
+- 详情：
+
+  是否在行内代码的 `<code>` 标签上添加 `v-pre` 指令。
+
+- 参考：
+  - [指南 > Markdown > 语法扩展 > 代码块 > 添加 v-pre](../guide/markdown.md#添加-v-pre)
+
 ## 插件配置
 
 ### plugins