feat: update markdown code docs

Mister-Hope · Mister-Hope · commit 69e0b63f4e74 · 2024-05-27T15:51:23.000+08:00
diff --git 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**
 
@@ -192,98 +192,6 @@ export default defineUserConfig({
 })
 ```
 
-It can be used in combination with the other marks below. Please leave a space between them.
-
-#### Line Highlighting
-
-You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks:
-
-**Input**
-
-````md
-```ts{1,7-9}
-import { defaultTheme } from '@vuepress/theme-default'
-import { defineUserConfig } from 'vuepress'
-
-export default defineUserConfig({
-  title: 'Hello, VuePress',
-
-  theme: defaultTheme({
-    logo: 'https://vuejs.org/images/logo.png',
-  }),
-})
-```
-````
-
-**Output**
-
-```ts{1,7-9}
-import { defaultTheme } from '@vuepress/theme-default'
-import { defineUserConfig } from 'vuepress'
-
-export default defineUserConfig({
-  title: 'Hello, VuePress',
-
-  theme: defaultTheme({
-    logo: 'https://vuejs.org/images/logo.png',
-  }),
-})
-```
-
-Examples for line ranges mark:
-
-- Line ranges: `{5-8}`
-- Multiple single lines: `{4,7,9}`
-- Combined: `{4,7-13,16,23-27,40}`
-
-::: tip
-This line highlighting extension is supported by our built-in plugin, which is forked and modified from [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines).
-
-Config reference: [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines)
-:::
-
-#### 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 can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
-
-**Input**
-
-````md
-```ts
-// line-numbers is enabled by default
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-
-```ts:no-line-numbers
-// line-numbers is disabled
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-````
-
-**Output**
-
-```ts
-// line-numbers is enabled by default
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-
-```ts:no-line-numbers
-// line-numbers is disabled
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-
-::: tip
-This line numbers extension is supported by our built-in plugin.
-
-Config reference: [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers)
-:::
-
 #### Wrap with v-pre
 
 As [template syntax is allowed in Markdown](#template-syntax), it would also work in code blocks, too.
@@ -346,7 +254,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
@@ -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
@@ -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
@@ -159,7 +159,7 @@ Emoji 扩展由 [markdown-it-emoji](https://github.com/markdown-it/markdown-it-e
 
 #### 代码标题
 
-你可以在代码块添加一个 `title` 键值对来为代码块设置标题。
+你可以在代码块添加一个 `title` 键值对来为代码块设置标题。提示：需要主题支持。
 
 **Input**
 
@@ -193,98 +193,6 @@ export default defineUserConfig({
 })
 ```
 
-它可以和下列的其他标记一起使用。请在它们之间使用空格分隔。
-
-#### 行高亮
-
-你可以在代码块添加行数范围标记，来为对应代码行进行高亮：
-
-**输入**
-
-````md
-```ts{1,7-9}
-import { defaultTheme } from '@vuepress/theme-default'
-import { defineUserConfig } from 'vuepress'
-
-export default defineUserConfig({
-  title: '你好， VuePress',
-
-  theme: defaultTheme({
-    logo: 'https://vuejs.org/images/logo.png',
-  }),
-})
-```
-````
-
-**输出**
-
-```ts{1,7-9}
-import { defaultTheme } from '@vuepress/theme-default'
-import { defineUserConfig } from 'vuepress'
-
-export default defineUserConfig({
-  title: '你好， VuePress',
-
-  theme: defaultTheme({
-    logo: 'https://vuejs.org/images/logo.png',
-  }),
-})
-```
-
-行数范围标记的例子：
-
-- 行数范围： `{5-8}`
-- 多个单行： `{4,7,9}`
-- 组合： `{4,7-13,16,23-27,40}`
-
-::: tip
-行高亮扩展是由我们的内置插件支持的，该扩展 Fork 并修改自 [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines)。
-
-配置参考： [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines)
-:::
-
-#### 行号
-
-你肯定已经注意到在代码块的最左侧会展示行号。这个功能是默认启用的，你可以通过配置来禁用它。
-
-你可以在代码块添加 `:line-numbers` / `:no-line-numbers` 标记来覆盖配置项中的设置。
-
-**输入**
-
-````md
-```ts
-// 行号默认是启用的
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-
-```ts:no-line-numbers
-// 行号被禁用
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-````
-
-**输出**
-
-```ts
-// 行号默认是启用的
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-
-```ts:no-line-numbers
-// 行号被禁用
-const line2 = 'This is line 2'
-const line3 = 'This is line 3'
-```
-
-::: tip
-行号扩展是由我们的内置插件支持的。
-
-配置参考： [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers)
-:::
-
 #### 添加 v-pre
 
 由于 [模板语法可以在 Markdown 中使用](#模板语法)，它也同样可以在代码块中生效。
@@ -347,7 +255,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
diff --git a/docs/zh/reference/config.md b/docs/zh/reference/config.md
