feat: markdown file inclusion support specify title

docs/en/guide/markdown.md

@@ -897,6 +897,40 @@ You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/co
 Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected.
 :::
 
+You can also specify a title:
+
+**Input**
+
+```md
+# Docs
+
+## Basics
+
+<!--@include: ./parts/basics.md{### Configuration}-->
+```
+
+**Part file** (`parts/basics.md`)
+
+```md
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+**Equivalent code**
+
+```md
+# Docs
+
+## Basics
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
 ## Math Equations
 
 This is currently opt-in. To enable it, you need to install `markdown-it-mathjax3` and set `markdown.math` to `true` in your config file:

src/node/utils/processIncludes.ts

@@ -14,17 +14,22 @@ export function processIncludes(
   const includesRE = /<!--\s*@include:\s*(.*?)\s*-->/g
   const regionRE = /(#[\w-]+)/
   const rangeRE = /\{(\d*),(\d*)\}$/
+  const titleRE = /(\{#+\s?[\w\s]+\})/
 
   return src.replace(includesRE, (m: string, m1: string) => {
     if (!m1.length) return m
 
     const range = m1.match(rangeRE)
-    const region = m1.match(regionRE)
+    const title = m1.match(titleRE)
+    const region = title ? null : m1.match(regionRE)
 
-    const hasMeta = !!(region || range)
+    const hasMeta = !!(region || range || title)
 
     if (hasMeta) {
-      const len = (region?.[0].length || 0) + (range?.[0].length || 0)
+      const len =
+        (region?.[0].length || 0) +
+        (range?.[0].length || 0) +
+        (title?.[0].length || 0)
       m1 = m1.slice(0, -len) // remove meta info from the include path
     }
 
@@ -54,6 +59,22 @@ export function processIncludes(
           .join('\n')
       }
 
+      if (title) {
+        const titleName = title[0].slice(1, -1).trim()
+        const lines = content.split(/\r?\n/)
+        const start = lines.findIndex((line) => line === titleName)
+        const prefixLength = titleName.replace(/[^#]/g, '').length
+        const end = lines.findIndex(
+          (line, index) =>
+            line.replace(/[^#]/g, '').length === prefixLength && index > start
+        )
+        if (end === -1) {
+          content = lines.slice(start).join('\n')
+        } else {
+          content = lines.slice(start, end).join('\n')
+        }
+      }
+
       if (!hasMeta && path.extname(includePath) === '.md') {
         content = matter(content).content
       }