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

@@ -0,0 +1,6 @@
+---
+author: John Smith
+date: 2020-1-1
+---
+
+> This is from the `example.md`

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.

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>

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;

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) {

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 = {};
 

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);