feat(metadata): add support for embedded metadata

A simple metadata parser can be useful in markdown documents. This commit introduces the feature, with the following syntax: --- or Â«Â«Â« at tstart of the document, (optionally) followed by a alphanumeric format identifier followed by key value pairs separated by a colon and a space followed by --- or ÂÂÂ Also, adds methods for retrieving the parsed metadata, namely: getMetadata() and getMetadataFormat Closes #260
showdownjs · Dec 10, 2017 · 63d949f · 63d949f · rugk · Jul 1, 2018
1 parent a8427c9
commit 63d949f
Show file tree

Hide file tree

Showing 31 changed files with 662 additions and 41 deletions.
diff --git a/dist/showdown.js b/dist/showdown.js
diff --git a/dist/showdown.js.map b/dist/showdown.js.map
diff --git a/dist/showdown.min.js b/dist/showdown.min.js
diff --git a/dist/showdown.min.js.map b/dist/showdown.min.js.map
diff --git a/src/converter.js b/src/converter.js
@@ -43,7 +43,17 @@ showdown.Converter = function (converterOptions) {
       /**
        * The flavor set in this converter
        */
-      setConvFlavor = setFlavor;
+      setConvFlavor = setFlavor,
+
+    /**
+     * Metadata of the document
+     * @type {{parsed: {}, raw: string, format: string}}
+     */
+      metadata = {
+        parsed: {},
+        raw: '',
+        format: ''
+      };
 
   _constructor();
 
@@ -255,7 +265,12 @@ showdown.Converter = function (converterOptions) {
       langExtensions:  langExtensions,
       outputModifiers: outputModifiers,
       converter:       this,
-      ghCodeBlocks:    []
+      ghCodeBlocks:    [],
+      metadata: {
+        parsed: {},
+        raw: '',
+        format: ''
+      }
     };
 
     // This lets us use ¨ trema as an escape char to avoid md5 hashes
@@ -299,6 +314,7 @@ showdown.Converter = function (converterOptions) {
     });
 
     // run the sub parsers
+    text = showdown.subParser('metadata')(text, options, globals);
     text = showdown.subParser('hashPreCodeTags')(text, options, globals);
     text = showdown.subParser('githubCodeBlocks')(text, options, globals);
     text = showdown.subParser('hashHTMLBlocks')(text, options, globals);
@@ -315,13 +331,15 @@ showdown.Converter = function (converterOptions) {
     text = text.replace(/¨T/g, '¨');
 
     // render a complete html document instead of a partial if the option is enabled
-    text = showdown.subParser('completeHTMLOutput')(text, options, globals);
+    text = showdown.subParser('completeHTMLDocument')(text, options, globals);
 
     // Run output modifiers
     showdown.helper.forEach(outputModifiers, function (ext) {
       text = showdown.subParser('runExtension')(ext, text, options, globals);
     });
 
+    // update metadata
+    metadata = globals.metadata;
     return text;
   };
 
@@ -429,4 +447,50 @@ showdown.Converter = function (converterOptions) {
       output: outputModifiers
     };
   };
+
+  /**
+   * Get the metadata of the previously parsed document
+   * @param raw
+   * @returns {string|{}}
+   */
+  this.getMetadata = function (raw) {
+    if (raw) {
+      return metadata.raw;
+    } else {
+      return metadata.parsed;
+    }
+  };
+
+  /**
+   * Get the metadata format of the previously parsed document
+   * @returns {string}
+   */
+  this.getMetadataFormat = function () {
+    return metadata.format;
+  };
+
+  /**
+   * Private: set a single key, value metadata pair
+   * @param {string} key
+   * @param {string} value
+   */
+  this._setMetadataPair = function (key, value) {
+    metadata.parsed[key] = value;
+  };
+
+  /**
+   * Private: set metadata format
+   * @param {string} format
+   */
+  this._setMetadataFormat = function (format) {
+    metadata.format = format;
+  };
+
+  /**
+   * Private: set metadata raw text
+   * @param {string} raw
+   */
+  this._setMetadataRaw = function (raw) {
+    metadata.raw = raw;
+  };
 };
diff --git a/src/options.js b/src/options.js
@@ -151,10 +151,15 @@ function getDefaultOpts (simple) {
       description: 'Enable support for underline. Syntax is double or triple underscores: `__underline word__`. With this option enabled, underscores no longer parses into `<em>` and `<strong>`',
       type: 'boolean'
     },
-    completeHTMLOutput: {
+    completeHTMLDocument: {
       defaultValue: false,
       description: 'Outputs a complete html document, including `<html>`, `<head>` and `<body>` tags',
       type: 'boolean'
+    },
+    metadata: {
+      defaultValue: false,
+      description: 'Enable support for document metadata (defined at the top of the document between `«««` and `»»»` or between `---` and `---`).',
+      type: 'boolean'
     }
   };
   if (simple === false) {