From 95a74e58a4969b44b6057aa4a1eb54b67d1bc325 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Eulier=20Gonz=C3=A1lez?= <eulier1@gmail.com>
Date: Fri, 8 Jul 2022 06:16:22 -0300
Subject: [PATCH] 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    | 42 +++++++++++++++++++++++++++++++++++++++
 src/node/markdownToVue.ts | 14 ++++++++-----
 2 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index 39716fef..342904e5 100644
--- a/docs/guide/markdown.md
+++ b/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`:
diff --git a/src/node/markdownToVue.ts b/src/node/markdownToVue.ts
index 86a07750..eeb567a3 100644
--- a/src/node/markdownToVue.ts
+++ b/src/node/markdownToVue.ts
@@ -54,11 +54,15 @@ export async function createMarkdownToVueRenderFn(
 
     // resolve includes
     let includes: string[] = []
-    src = src.replace(includesRE, (_, m1) => {
-      const includePath = path.join(dir, m1)
-      const content = fs.readFileSync(includePath, 'utf-8')
-      includes.push(slash(includePath))
-      return content
+    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)