docs: add including markdown content to guide (#938)

Co-authored-by: Eulier <eulier@toolboxos.com>
Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>

docs/guide/markdown.md

@@ -388,6 +388,48 @@ You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/co
 
 <!--lint enable strong-marker-->
 
+## Markdown File Inclusion
+
+You can include a markdown file in another markdown file like this:
+
+**Input**
+
+```md
+# Docs
+
+## Basics
+
+<!--@include: ./parts/basics.md-->
+```
+
+**Part file** (`parts/basics.md`)
+
+```md
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+**Equivalent code**
+
+```md
+# Docs
+
+## Basics
+
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+::: warning
+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.
+:::
+
 ## Advanced Configuration
 
 VitePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vitepress/config.js`:

src/node/markdownToVue.ts

@@ -54,11 +54,15 @@ export async function createMarkdownToVueRenderFn(
 
     // resolve includes
     let includes: string[] = []
-    src = src.replace(includesRE, (_, m1) => {
+    src = src.replace(includesRE, (m, m1) => {
+      try {
         const includePath = path.join(dir, m1)
         const content = fs.readFileSync(includePath, 'utf-8')
         includes.push(slash(includePath))
         return content
+      } catch (error) {
+        return m // silently ignore error if file is not present
+      }
     })
 
     const { content, data: frontmatter } = matter(src)