Support parsing and removing a YAML metadata block in markdown.

code/DocumentationParser.php

@@ -522,36 +522,4 @@ class DocumentationParser
         return $md;
     }
 
-    /**
-     * Strips out the metadata for a page
-     *
-     * @param DocumentationPage
-     */
-    public static function retrieve_meta_data(DocumentationPage $page)
-    {
-        $md = $page->getMarkdown();
-        if ($md) {
-            // get the text up to the first empty line
-            $extPattern = "/^(.+)\n\r*\n/Uis";
-            $matches = preg_match($extPattern, $md, $block);
-
-            if ($matches && $block[1]) {
-
-                // find the key/value pairs
-                $lines = preg_split('/\v+/', $block[1]);
-                $key = '';
-                $value = '';
-                foreach ($lines as $line) {
-                    if (strpos($line, ':') !== false) {
-                        list($key, $value) = explode(':', $line, 2);
-                        $key = trim($key);
-                        $value = trim($value);
-                    } else {
-                        $value .= ' ' . trim($line);
-                    }
-                    $page->setMetaData($key, $value);
-                }
-            }
-        }
-    }
 }

code/models/DocumentationPage.php

@@ -172,13 +172,6 @@ class DocumentationPage extends ViewableData
         return false;
     }
 
-    public function setMetaData($key, $value)
-    {
-        $key = strtolower($key);
-
-        $this->$key = $value;
-    }
-
     /**
      * @return string
      */
@@ -280,7 +273,37 @@ class DocumentationPage extends ViewableData
      */
     public function populateMetaDataFromText(&$md, $removeMetaData = false)
     {
-        if ($md) {
+        if (!$md) {
+            return;
+        }
+
+        // See if there is YAML metadata block at the top of the document. e.g.
+        // ---
+        // property: value
+        // another: value
+        // ---
+        //
+        // If we found one, then we'll use a YAML parser to extract the
+        // data out and then remove the whole block from the markdown string.
+        $parser = new \Mni\FrontYAML\Parser();
+        $document = $parser->parse($md, false);
+        $yaml = $document->getYAML();
+        if ($yaml) {
+            foreach ($yaml as $key => $value) {
+                if (!property_exists(get_class($this), $key)) {
+                    continue;
+                }
+                $this->$key = $value;
+            }
+            if ($removeMetaData) {
+                $md = $document->getContent();
+            }
+            return;
+        }
+
+        // this is the alternative way of parsing the properties out that don't contain
+        // a YAML block declared with ---
+        //
         // get the text up to the first empty line
         $extPattern = "/^(.+)\n\r*\n/Uis";
         $matches = preg_match($extPattern, $md, $block);
@@ -313,7 +336,6 @@ class DocumentationPage extends ViewableData
             }
         }
     }
-    }
 
     public function getVersion()
     {
@@ -328,3 +350,4 @@ class DocumentationPage extends ViewableData
         return sprintf(get_class($this) .': %s)', $this->getPath());
     }
 }
+

composer.json

@@ -16,7 +16,8 @@
 	"require": {
         "silverstripe/framework": "~3.1",
         "erusev/parsedown-extra": "0.2.2",
-		"erusev/parsedown": "~1.1.0"
+        "erusev/parsedown": "~1.1.0",
+        "mnapoli/front-yaml": "^1.5"
     },
     "suggest": {
         "silverstripe/staticpublisher": "Allows publishing documentation as HTML"

tests/DocumentationParserTest.php

@@ -128,7 +128,6 @@ with multiple
 lines
 	and tab indent
 	and escaped < brackets
-	
 ```
 Normal text after code block
 HTML;
@@ -395,12 +394,39 @@ HTML;
 
     public function testRetrieveMetaData()
     {
-        DocumentationParser::retrieve_meta_data($this->metaDataPage);
+        $this->metaDataPage->getMarkdown(true);
+        $this->assertEquals('Foo Bar\'s Test page.', $this->metaDataPage->getTitle());
+        $this->assertEquals('A long intro that splits over many lines', $this->metaDataPage->getIntroduction());
+        $this->assertEquals('Foo Bar Test page description', $this->metaDataPage->getSummary());
 
-        $this->assertEquals('Dr. Foo Bar.', $this->metaDataPage->author);
-        $this->assertEquals("Foo Bar's Test page.", $this->metaDataPage->getTitle());
-        $this->assertEquals("Foo Bar's Test page.", $this->metaDataPage->getTitle());
-        $this->assertEquals("A long intro that splits over many lines", $this->metaDataPage->getIntroduction());
+        $parsed = DocumentationParser::parse($this->metaDataPage);
+        $expected = <<<HTML
+<h1 id="content">Content</h1>
+HTML;
+        $this->assertEquals($parsed, $expected, 'Metadata block removed, parsed correctly');
+    }
+
+    public function testRetrieveMetaDataYamlBlock()
+    {
+        $page = new DocumentationPage(
+            $this->entityAlt,
+            'MetaDataYamlBlockTest.md',
+            DOCSVIEWER_PATH . '/tests/docs-parser/en/MetaDataYamlBlockTest.md'
+        );
+        $page->getMarkdown(true);
+
+        $this->assertEquals('Foo Bar\'s Test page.', $page->getTitle());
+        $this->assertEquals('This is the page\'s description', $page->getSummary());
+
+        $parsed = DocumentationParser::parse($page);
+        $expected = <<<HTML
+<h2 id="content-2">Content</h2>
+<p>Content goes here.</p>
+<hr />
+<h2>randomblock: ignored</h2>
+HTML;
+
+        $this->assertEquals($parsed, $expected, 'YAML metadata block removed, parsed correctly');
     }
 
     public function testRewritingRelativeLinksToFiles()

tests/docs-parser/en/MetaDataTest.md

@@ -1,7 +1,6 @@
-Title: Foo Bar's Test page.
-Author: Dr. Foo Bar.
-Another: Test.
-Introduction: A long intro that
+title: Foo Bar's Test page.
+summary: Foo Bar Test page description
+introduction: A long intro that
 splits over
 many lines
 

tests/docs-parser/en/MetaDataYamlBlockTest.md

@@ -0,0 +1,13 @@
+---
+title: "Foo Bar's Test page."
+summary: "This is the page's description"
+
+---
+
+## Content
+
+Content goes here.
+
+---
+randomblock: ignored
+---

tests/docs/en/test.md

@@ -30,7 +30,6 @@ test
 		and tab indent
 		and escaped < brackets
 
-
 Normal text after code block
 
 	code block