feat(markdown): include all regions with same name

VitePress supports including a part of a file through a VS Code region.
However, when multiple regions have the same name, only one is included.

The workaround plugin suggested in #3690 is no longer maintained. [^1]
Furthermore, it suffers from a memory leak causing huge RAM usage. [^2]
While we at Fabric Docs have forked the plugin [^3] to fix some issues,
it still feels fragile. Another problem is having to use two different
syntaxes (`<<<` vs `@[]()`) for including files, which caused confusion.

Since this feature has been requested by VitePress directly, I don't
think there's any point in trying to fix the plugin any further.

fix #3690

[^1]: <fabioaanthony/markdown-it-vuepress-code-snippet-enhanced#7>
[^2]: <https://discord.com/channels/507304429255393322/1208846408552030238/1407245292482330695> via <https://discord.gg/v6v4pMv>
[^3]: <https://github.com/IMB11/md-it-enhanced-snippets>

Author: its-miroma

docs/en/guide/markdown.md

@@ -656,12 +656,12 @@ The value of `@` corresponds to the source root. By default it's the VitePress p
 
 :::
 
-You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath:
+You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath, and all regions with that name will be imported:
 
 **Input**
 
 ```md
-<<< @/snippets/snippet-with-region.js#snippet{1}
+<<< @/snippets/snippet-with-region.js#snippet{2,5}
 ```
 
 **Code file**
@@ -670,7 +670,7 @@ You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/co
 
 **Output**
 
-<<< @/snippets/snippet-with-region.js#snippet{1}
+<<< @/snippets/snippet-with-region.js#snippet{2,5}
 
 You can also specify the language inside the braces (`{}`) like this:
 
@@ -856,7 +856,7 @@ Can be created using `.foorc.json`.
 
 The format of the selected line range can be: `{3,}`, `{,10}`, `{1,10}`
 
-You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath:
+You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath, and all regions with that name will be included:
 
 **Input**
 

docs/snippets/snippet-with-region.js

@@ -1,7 +1,15 @@
 // #region snippet
 function foo() {
-  // ..
+  console.log('foo')
 }
 // #endregion snippet
 
-export default foo
+console.log('this line is not in #region snippet!')
+
+// #region snippet
+function bar() {
+  console.log('bar')
+}
+// #endregion snippet
+
+export { bar, foo }

src/node/markdown/plugins/snippet.ts

@@ -86,37 +86,44 @@ const markers = [
   }
 ]
 
-export function findRegion(lines: Array<string>, regionName: string) {
-  let chosen: { re: (typeof markers)[number]; start: number } | null = null
-  // find the regex pair for a start marker that matches the given region name
-  for (let i = 0; i < lines.length; i++) {
-    for (const re of markers) {
-      if (re.start.exec(lines[i])?.[1] === regionName) {
-        chosen = { re, start: i + 1 }
-        break
+export function findRegions(lines: Array<string>, regionName: string) {
+  const returned: {
+    re: (typeof markers)[number]
+    start: number
+    end: number
+  }[] = []
+
+  for (const re of markers) {
+    let nestedCounter = 0
+    let start: number | null = null
+
+    for (let i = 0; i < lines.length; i++) {
+      // find region start
+      const startMatch = re.start.exec(lines[i])
+      if (startMatch?.[1] === regionName) {
+        if (nestedCounter === 0) start = i + 1
+        nestedCounter++
+        continue
+      }
+
+      if (nestedCounter === 0) continue
+
+      // find region end
+      const endMatch = re.end.exec(lines[i])
+      if (endMatch?.[1] === regionName || endMatch?.[1] === '') {
+        nestedCounter--
+        // if all nested regions ended
+        if (nestedCounter === 0 && start != null) {
+          returned.push({ re, start, end: i })
+          start = null
+        }
       }
     }
-    if (chosen) break
-  }
-  if (!chosen) return null
-
-  let counter = 1
-  // scan the rest of the lines to find the matching end marker, handling nested markers
-  for (let i = chosen.start; i < lines.length; i++) {
-    // check for an inner start marker for the same region
-    if (chosen.re.start.exec(lines[i])?.[1] === regionName) {
-      counter++
-      continue
-    }
-    // check for an end marker for the same region
-    const endRegion = chosen.re.end.exec(lines[i])?.[1]
-    // allow empty region name on the end marker as a fallback
-    if (endRegion === regionName || endRegion === '') {
-      if (--counter === 0) return { ...chosen, end: i }
-    }
+
+    if (returned.length > 0) break
   }
 
-  return null
+  return returned
 }
 
 export const snippetPlugin = (md: MarkdownItAsync, srcDir: string) => {
@@ -183,11 +190,14 @@ export const snippetPlugin = (md: MarkdownItAsync, srcDir: string) => {
       includes.push(src)
     }
 
-    const isAFile = fs.statSync(src).isFile()
-    if (!fs.existsSync(src) || !isAFile) {
-      token.content = isAFile
-        ? `Code snippet path not found: ${src}`
-        : `Invalid code snippet option`
+    if (!fs.existsSync(src)) {
+      token.content = `Code snippet path not found: ${src}`
+      token.info = ''
+      return fence(...args)
+    }
+
+    if (!fs.statSync(src).isFile()) {
+      token.content = `Invalid code snippet option`
       token.info = ''
       return fence(...args)
     }
@@ -196,13 +206,16 @@ export const snippetPlugin = (md: MarkdownItAsync, srcDir: string) => {
 
     if (regionName) {
       const lines = content.split('\n')
-      const region = findRegion(lines, regionName)
+      const regions = findRegions(lines, regionName)
 
-      if (region) {
+      if (regions.length > 0) {
         content = dedent(
-          lines
-            .slice(region.start, region.end)
-            .filter((l) => !(region.re.start.test(l) || region.re.end.test(l)))
+          regions
+            .flatMap((r) =>
+              lines
+                .slice(r.start, r.end)
+                .filter((l) => !(r.re.start.test(l) || r.re.end.test(l)))
+            )
             .join('\n')
         )
       }

src/node/utils/processIncludes.ts

@@ -3,7 +3,7 @@ import matter from 'gray-matter'
 import type { MarkdownItAsync } from 'markdown-it-async'
 import path from 'node:path'
 import c from 'picocolors'
-import { findRegion } from '../markdown/plugins/snippet'
+import { findRegions } from '../markdown/plugins/snippet'
 import { slash, type MarkdownEnv } from '../shared'
 
 export function processIncludes(
@@ -42,9 +42,9 @@ export function processIncludes(
       if (region) {
         const [regionName] = region
         const lines = content.split(/\r?\n/)
-        let { start, end } = findRegion(lines, regionName.slice(1)) ?? {}
+        let regions = findRegions(lines, regionName.slice(1))
 
-        if (start === undefined) {
+        if (regions.length === 0) {
           // region not found, it might be a header
           const tokens = md
             .parse(content, {
@@ -58,18 +58,22 @@ export function processIncludes(
           )
           const token = tokens[idx]
           if (token) {
-            start = token.map![1]
+            const start = token.map![1]
             const level = parseInt(token.tag.slice(1))
+            let end = undefined
             for (let i = idx + 1; i < tokens.length; i++) {
               if (parseInt(tokens[i].tag.slice(1)) <= level) {
                 end = tokens[i].map![0]
                 break
               }
             }
+            regions.push({ start, end } as any)
           }
         }
 
-        content = lines.slice(start, end).join('\n')
+        content = regions
+          .flatMap((region) => lines.slice(region.start, region.end))
+          .join('\n')
       }
 
       if (range) {
@@ -97,11 +101,9 @@ export function processIncludes(
         includes,
         cleanUrls
       )
-
-      //
     } catch (error) {
       if (process.env.DEBUG) {
-        process.stderr.write(c.yellow(`\nInclude file not found: ${m1}`))
+        process.stderr.write(c.yellow(`Include file not found: ${m1}\n`))
       }
 
       return m // silently ignore error if file is not present