abstracted annotations.md markdown parser into a shared component

 - all existing tests pass
 - patternState and many other keys are now parsed out of pattern.md
- supports pseudopatterns too

#376

Author: bmuenzenmeyer

core/lib/annotation_exporter.js

@@ -1,12 +1,14 @@
 "use strict";
 
+var path = require('path'),
+  fs = require('fs-extra'),
+  JSON5 = require('json5'),
+  _ = require('lodash'),
+  mp = require('./markdown_parser');
+
 var annotations_exporter = function (pl) {
-  var path = require('path'),
-    fs = require('fs-extra'),
-    JSON5 = require('json5'),
-    _ = require('lodash'),
-    md = require('markdown-it')(),
-    paths = pl.config.paths;
+
+  var paths = pl.config.paths;
 
   /*
   Returns the array of comments that used to be wrapped in raw JS.
@@ -38,6 +40,7 @@ var annotations_exporter = function (pl) {
    Converts the annotations.md file yaml list into an array of annotations
    */
   function parseAnnotationsMD() {
+    var markdown_parser = new mp();
     var annotations = [];
 
     //attempt to read the file
@@ -53,51 +56,25 @@ var annotations_exporter = function (pl) {
 
     //take the annotation snippets and split them on our custom delimiter
     var annotationsYAML = annotationsMD.split('~*~');
+
     for (var i = 0; i < annotationsYAML.length; i++) {
       var annotation = {};
 
-      //for each annotation process the yaml frontmatter and markdown
-      var annotationSnippet = annotationsYAML[i];
-      var annotationsRE = /---\r?\n{1}([\s\S]*)---\r?\n{1}([\s\S]*)+/gm;
-      var chunks = annotationsRE.exec(annotationSnippet);
-      if (chunks && chunks[1] && chunks[2]) {
-
-        //convert each yaml frontmatter key into an object key
-        var frontmatter = chunks[1];
-        var frontmatterLines = frontmatter.split(/\n/gm);
-        for (var j = 0; j < frontmatterLines.length; j++) {
-          var frontmatterLine = frontmatterLines[j];
-          if (frontmatterLine.length > 0) {
-            var frontmatterLineChunks = frontmatterLine.split(':'); //test this
-            var frontmatterKey = frontmatterLineChunks[0].toLowerCase().trim();
-            var frontmatterValueString = frontmatterLineChunks[1].trim();
-            var frontmatterValue = frontmatterValueString.substring(1, frontmatterValueString.length - 1);
-            if (frontmatterKey === 'el' || frontmatterKey === 'selector') {
-              annotation.el = frontmatterValue;
-            }
-            if (frontmatterKey === 'title') {
-              annotation.title = frontmatterValue;
-            }
-          }
-        }
-
-        //set the comment to the parsed markdown
-        var annotationMarkdown = chunks[2];
-        annotation.comment = md.render(annotationMarkdown);
-
-        annotations.push(annotation);
-      } else {
-        console.log('annotations.md file not formatted as expected. Error parsing frontmatter and markdown out of ' + annotationSnippet);
-      }
+      var markdownObj = markdown_parser.parse(annotationsYAML[i]);
+
+      annotation.el = markdownObj.el || markdownObj.selector;
+      annotation.title = markdownObj.title;
+      annotation.comment = markdownObj.markdown;
+
+      annotations.push(annotation);
     }
     return annotations;
   }
 
   function gatherAnnotations() {
     var annotationsJS = parseAnnotationsJS();
     var annotationsMD = parseAnnotationsMD();
-    var mergedAnnotations = _.unionBy(annotationsJS, annotationsMD, 'el');
-    return mergedAnnotations;
+    return _.unionBy(annotationsJS, annotationsMD, 'el');
   }
 
   return {

core/lib/markdown_parser.js

@@ -0,0 +1,53 @@
+"use strict";
+
+var md = require('markdown-it')();
+
+var markdown_parser = function () {
+
+  function parseMarkdownBlock(block) {
+    var returnObject = {};
+
+    try {
+      //for each block process the yaml frontmatter and markdown
+      var frontmatterRE = /---\r?\n{1}([\s\S]*)---\r?\n{1}([\s\S]*)+/gm;
+      var chunks = frontmatterRE.exec(block);
+      if (chunks && chunks[1] && chunks[2]) {
+
+        //convert each yaml frontmatter key / value into an object key
+        var frontmatter = chunks[1];
+        var frontmatterLines = frontmatter.split(/\n/gm);
+        for (var j = 0; j < frontmatterLines.length; j++) {
+
+          var frontmatterLine = frontmatterLines[j];
+          if (frontmatterLine.length > 0) {
+
+            var frontmatterLineChunks = frontmatterLine.split(':'); //test this
+            var frontmatterKey = frontmatterLineChunks[0].toLowerCase().trim();
+            var frontmatterValueString = frontmatterLineChunks[1].trim();
+
+            returnObject[frontmatterKey] = frontmatterValueString.substring(1, frontmatterValueString.length - 1);
+          }
+
+        }
+
+        //parse the actual markdown
+        returnObject.markdown = md.render(chunks[2]);
+      }
+    } catch (ex) {
+      console.log(ex);
+      console.log('error parsing markdown block', block);
+    }
+
+    //return the frontmatter keys and markdown for a consumer to decide what to do with
+    return returnObject;
+  }
+
+  return {
+    parse: function (block) {
+      return parseMarkdownBlock(block);
+    }
+  };
+
+};
+
+module.exports = markdown_parser;

core/lib/pattern_assembler.js

@@ -5,7 +5,7 @@ var pattern_assembler = function () {
     fs = require('fs-extra'),
     Pattern = require('./object_factory').Pattern,
     pph = require('./pseudopattern_hunter'),
-    md = require('markdown-it')(),
+    mp = require('./markdown_parser'),
     plutils = require('./utilities'),
     patternEngines = require('./pattern_engines');
 
@@ -66,6 +66,9 @@ var pattern_assembler = function () {
     }
   }
 
+  /*
+   * Deprecated in favor of .md 'status' frontmatter inside a pattern. Still used for unit tests at this time.
+   */
   function setState(pattern, patternlab) {
     if (patternlab.config.patternStates && patternlab.config.patternStates[pattern.patternPartial]) {
       pattern.patternState = patternlab.config.patternStates[pattern.patternPartial];
@@ -123,6 +126,54 @@ var pattern_assembler = function () {
     }
   }
 
+  function parsePatternMarkdown(currentPattern, patternlab) {
+
+    var markdown_parser = new mp();
+
+    try {
+      var markdownFileName = path.resolve(patternlab.config.paths.source.patterns, currentPattern.subdir, currentPattern.fileName + ".md");
+      var markdownFileContents = fs.readFileSync(markdownFileName, 'utf8');
+
+      var markdownObject = markdown_parser.parse(markdownFileContents);
+      if (!plutils.isObjectEmpty(markdownObject)) {
+        //set keys and markdown itself
+        currentPattern.patternDescExists = true;
+        currentPattern.patternDesc = markdownObject.markdown;
+
+        //consider looping through all keys eventually. would need to blacklist some properties and whitelist others
+        if (markdownObject.status) {
+          currentPattern.patternState = markdownObject.status;
+        }
+        if (markdownObject.order) {
+          currentPattern.order = markdownObject.order;
+        }
+        if (markdownObject.hidden) {
+          currentPattern.hidden = markdownObject.hidden;
+        }
+        if (markdownObject.excludeFromStyleguide) {
+          currentPattern.excludeFromStyleguide = markdownObject.excludeFromStyleguide;
+        }
+        if (markdownObject.tags) {
+          currentPattern.tags = markdownObject.tags;
+        }
+        if (markdownObject.links) {
+          currentPattern.links = markdownObject.links;
+        }
+      } else {
+        if (patternlab.config.debug) {
+          console.log('error processing markdown for ' + currentPattern.patternPartial);
+        }
+      }
+
+      if (patternlab.config.debug) {
+        console.log('found pattern-specific markdown for ' + currentPattern.patternPartial);
+      }
+    }
+    catch (e) {
+      // do nothing
+    }
+  }
+
   function processPatternIterative(relPath, patternlab) {
 
     var pseudopattern_hunter = new pph();
@@ -149,7 +200,7 @@ var pattern_assembler = function () {
     }
 
     //see if this file has a state
-    setState(currentPattern, patternlab);
+    //setState(currentPattern, patternlab);
 
     //look for a json file for this template
     try {
@@ -193,18 +244,7 @@ var pattern_assembler = function () {
     }
 
     //look for a markdown file for this template
-    try {
-      var markdownFileName = path.resolve(patternlab.config.paths.source.patterns, currentPattern.subdir, currentPattern.fileName + ".md");
-      var markdownFileContents = fs.readFileSync(markdownFileName, 'utf8');
-      currentPattern.patternDescExists = true;
-      currentPattern.patternDesc = md.render(markdownFileContents);
-      if (patternlab.config.debug) {
-        console.log('found pattern-specific markdown-documentation.md for ' + currentPattern.patternPartial);
-      }
-    }
-    catch (e) {
-      // do nothing
-    }
+    parsePatternMarkdown(currentPattern, patternlab);
 
     //add the raw template to memory
     currentPattern.template = fs.readFileSync(path.resolve(patternsPath, relPath), 'utf8');
@@ -397,6 +437,9 @@ var pattern_assembler = function () {
     },
     parse_data_links_specific: function (patternlab, data, label) {
       return parseDataLinksHelper(patternlab, data, label)
+    },
+    parse_pattern_markdown: function (pattern, patternlab) {
+      parsePatternMarkdown(pattern, patternlab);
     }
   };
 

core/lib/pseudopattern_hunter.js

@@ -38,7 +38,7 @@ var pseudopattern_hunter = function () {
           console.log('There was an error parsing pseudopattern JSON for ' + currentPattern.relPath);
           console.log(err);
         }
-        
+
         //extend any existing data with variant data
         variantFileData = plutils.mergeData(currentPattern.jsonFileData, variantFileData);
 
@@ -56,8 +56,8 @@ var pseudopattern_hunter = function () {
           engine: currentPattern.engine
         });
 
-        //see if this file has a state
-        pattern_assembler.setPatternState(patternVariant, patternlab);
+        //process the companion markdown file if it exists
+        pattern_assembler.parse_pattern_markdown(patternVariant, patternlab);
 
         //find pattern lineage
         lineage_hunter.find_lineage(patternVariant, patternlab);

patternlab-config.json

@@ -51,7 +51,6 @@
   "ishMaximum": "2600",
   "patternStateCascade": ["inprogress", "inreview", "complete"],
   "patternStates": {
-    "molecules-block-hero" : "inreview"
   },
   "patternExportPatternPartials": [],
   "patternExportDirectory": "./pattern_exports/",