From b05949a1615a0358e58cf1fd9007cc42c1af319f Mon Sep 17 00:00:00 2001
From: Sytone <github@sytone.com>
Date: Mon, 27 Apr 2020 12:24:24 -0700
Subject: [PATCH] Add front matter to dev page Update embeded files
 documentation Add example with front matter Add various comments I used to
 understand code Updated front matter to have installed flag Added function to
 parse front matter Added intercept to remove front matter for embed

---
 docs/_media/example-with-yaml.md  |  6 ++++++
 docs/embed-files.md               | 14 +++++++++++++-
 index.html                        |  1 +
 src/core/render/compiler.js       | 15 +++++++++++++++
 src/core/render/embed.js          |  7 +++++++
 src/core/render/utils.js          | 20 ++++++++++++++++++++
 src/plugins/front-matter/index.js |  8 ++++++++
 7 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 docs/_media/example-with-yaml.md

diff --git a/docs/_media/example-with-yaml.md b/docs/_media/example-with-yaml.md
new file mode 100644
index 000000000..081bedde2
--- /dev/null
+++ b/docs/_media/example-with-yaml.md
@@ -0,0 +1,6 @@
+---
+author: John Smith
+date: 2020-1-1
+---
+
+> This is from the `example.md`
diff --git a/docs/embed-files.md b/docs/embed-files.md
index dab2efe4e..d50387477 100644
--- a/docs/embed-files.md
+++ b/docs/embed-files.md
@@ -39,7 +39,20 @@ You will get it
 
 [filename](_media/example.md ':include :type=code')
 
+## Markdown with YAML Front Matter
+
+When using Markdown, YAML front matter will be stripped from the rendered content. The attributes cannot be used in this case.
+
+```markdown
+[filename](_media/example-with-yaml.md ':include')
+```
+
+You will get just the content
+
+[filename](_media/example-with-yaml.md ':include')
+
 ## Embedded code fragments
+
 Sometimes you don't want to embed a whole file. Maybe because you need just a few lines but you want to compile and test the file in CI.
 
 ```markdown
@@ -53,7 +66,6 @@ Example:
 
 [filename](_media/example.js ':include :type=code :fragment=demo')
 
-
 ## Tag attribute
 
 If you embed the file as `iframe`, `audio` and `video`, then you may need to set the attributes of these tags.
diff --git a/index.html b/index.html
index 59e6911bd..fba1a4074 100644
--- a/index.html
+++ b/index.html
@@ -76,6 +76,7 @@
   </script>
   <script src="/lib/docsify.js"></script>
   <script src="/lib/plugins/search.js"></script>
+  <script src="/lib/plugins/front-matter.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-nginx.min.js"></script>
diff --git a/src/core/render/compiler.js b/src/core/render/compiler.js
index c4c026205..5cb8f9e5a 100644
--- a/src/core/render/compiler.js
+++ b/src/core/render/compiler.js
@@ -121,6 +121,21 @@ export class Compiler {
     };
   }
 
+  /**
+   * Pulls content from file and renders inline on the page as a embedded item.
+   *
+   * This allows you to embed different file types on the returned
+   * page.
+   * The basic format is:
+   * ```
+   *   [filename](_media/example.md ':include')
+   * ```
+   *
+   * @param {string}   href   The href to the file to embed in the page.
+   * @param {string}   title  Title of the link used to make the embed.
+   *
+   * @return {type} Return value description.
+   */
   compileEmbed(href, title) {
     const { str, config } = getAndRemoveConfig(title);
     let embed;
diff --git a/src/core/render/embed.js b/src/core/render/embed.js
index 083fb7f97..8b84c7acb 100644
--- a/src/core/render/embed.js
+++ b/src/core/render/embed.js
@@ -36,6 +36,13 @@ function walkFetchEmbed({ embedTokens, compile, fetch }, cb) {
               return x;
             });
 
+            // This may contain YAML front matter and will need to be stripped.
+            const frontMatterInstalled =
+              ($docsify.frontMatter || {}).installed || false;
+            if (frontMatterInstalled === true) {
+              text = $docsify.frontMatter.parseMarkdown(text);
+            }
+
             embedToken = compile.lexer(text);
           } else if (token.embed.type === 'code') {
             if (token.embed.fragment) {
diff --git a/src/core/render/utils.js b/src/core/render/utils.js
index 6f2d14fa3..100d595cd 100644
--- a/src/core/render/utils.js
+++ b/src/core/render/utils.js
@@ -1,3 +1,23 @@
+/**
+ * Converts a colon formatted string to a object with properties.
+ *
+ * This is process a provided string and look for any tokens in the format
+ * of `:name[=value]` and then convert it to a object and return.
+ * An example of this is ':include :type=code :fragment=demo' is taken and
+ * then converted to:
+ *
+ * ```
+ * {
+ *  include: '',
+ *  type: 'code',
+ *  fragment: 'demo'
+ * }
+ * ```
+ *
+ * @param {string}   str   The string to parse.
+ *
+ * @return {object}  The original string and parsed object, { str, config }.
+ */
 export function getAndRemoveConfig(str = '') {
   const config = {};
 
diff --git a/src/plugins/front-matter/index.js b/src/plugins/front-matter/index.js
index e91c4efc3..a0aac5b63 100644
--- a/src/plugins/front-matter/index.js
+++ b/src/plugins/front-matter/index.js
@@ -1,6 +1,14 @@
 import parser from './parser';
 
 const install = function(hook, vm) {
+  // Used to remove front matter from embedded pages if installed.
+  vm.config.frontMatter = {};
+  vm.config.frontMatter.installed = true;
+  vm.config.frontMatter.parseMarkdown = function(content) {
+    const { body } = parser(content);
+    return body;
+  };
+
   hook.beforeEach(content => {
     const { attributes, body } = parser(content);