feat: support for customizing the starting line number in a code block (

#2917)

docs/guide/markdown.md

@@ -510,6 +510,8 @@ Please see [`markdown` options](../reference/site-config#markdown) for more deta
 
 You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config.
 
+You can also customize the starting line number by adding `=` after `:line-numbers`. For example, `:line-numbers=2` means the line numbers in code blocks will start from `2`.
+
 **Input**
 
 ````md
@@ -524,6 +526,12 @@ const line3 = 'This is line 3'
 const line2 = 'This is line 2'
 const line3 = 'This is line 3'
 ```
+
+```ts:line-numbers=2 {1}
+// line-numbers is enabled and start from 2
+const line3 = 'This is line 3'
+const line4 = 'This is line 4'
+```
 ````
 
 **Output**
@@ -540,6 +548,12 @@ const line2 = 'This is line 2'
 const line3 = 'This is line 3'
 ```
 
+```ts:line-numbers=2 {1}
+// line-numbers is enabled and start from 2
+const line3 = 'This is line 3'
+const line4 = 'This is line 4'
+````
+
 ## Import Code Snippets
 
 You can import code snippets from existing files via following syntax:
@@ -566,7 +580,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
 
 **Output**
 
-<<< @/snippets/snippet.js{2}
+<<< @/snippets/snippet.js
 
 ::: tip
 The value of `@` corresponds to the source root. By default it's the VitePress project root, unless `srcDir` is configured. Alternatively, you can also import from relative paths:

src/node/markdown/plugins/highlight.ts

@@ -87,7 +87,7 @@ export async function highlight(
   const styleRE = /<pre[^>]*(style=".*?")/
   const preRE = /^<pre(.*?)>/
   const vueRE = /-vue$/
-  const lineNoRE = /:(no-)?line-numbers$/
+  const lineNoRE = /:(no-)?line-numbers(=\d*)?$/
   const mustacheRE = /\{\{.*?\}\}/g
 
   return (str: string, lang: string, attrs: string) => {

src/node/markdown/plugins/lineNumbers.ts

@@ -12,12 +12,18 @@ export const lineNumberPlugin = (md: MarkdownIt, enable = false) => {
     const info = tokens[idx].info
 
     if (
-      (!enable && !/:line-numbers($| )/.test(info)) ||
+      (!enable && !/:line-numbers($| |=)/.test(info)) ||
       (enable && /:no-line-numbers($| )/.test(info))
     ) {
       return rawCode
     }
 
+    let startLineNumber = 1
+    const matchStartLineNumber = info.match(/:line-numbers=(\d*)/)
+    if (matchStartLineNumber && matchStartLineNumber[1]) {
+      startLineNumber = parseInt(matchStartLineNumber[1])
+    }
+
     const code = rawCode.slice(
       rawCode.indexOf('<code>'),
       rawCode.indexOf('</code>')
@@ -26,7 +32,10 @@ export const lineNumberPlugin = (md: MarkdownIt, enable = false) => {
     const lines = code.split('\n')
 
     const lineNumbersCode = [...Array(lines.length)]
-      .map((_, index) => `<span class="line-number">${index + 1}</span><br>`)
+      .map(
+        (_, index) =>
+          `<span class="line-number">${index + startLineNumber}</span><br>`
+      )
       .join('')
 
     const lineNumbersWrapperCode = `<div class="line-numbers-wrapper" aria-hidden="true">${lineNumbersCode}</div>`

src/node/markdown/plugins/preWrapper.ts

@@ -40,7 +40,7 @@ export function extractTitle(info: string, html = false) {
 function extractLang(info: string) {
   return info
     .trim()
-    .replace(/:(no-)?line-numbers({| |$).*/, '')
+    .replace(/:(no-)?line-numbers({| |$|=\d*).*/, '')
     .replace(/(-vue|{| ).*$/, '')
     .replace(/^vue-html$/, 'template')
     .replace(/^ansi$/, '')