tonyair/silverstripe-docsviewer
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-docsviewer synced 2024-10-22 09:05:56 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #131 from silverstripe/yaml-metadata-block

Browse Source 
Support parsing and removing a YAML metadata block in markdown.
This commit is contained in:
Mateusz U 2017-03-22 10:00:19 +13:00 committed by GitHub
commit f61751b19e
7 changed files with 152 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
code/DocumentationParser.php
View File

@ -522,36 +522,4 @@ class DocumentationParser
return $md; 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);
}
}
}
}
} }

91
code/models/DocumentationPage.php
View File

@ -172,13 +172,6 @@ class DocumentationPage extends ViewableData
return false; return false;
} }
public function setMetaData($key, $value)
{
$key = strtolower($key);
$this->$key = $value;
}
/** /**
* @return string * @return string
*/ */
@ -280,37 +273,66 @@ class DocumentationPage extends ViewableData
*/ */
public function populateMetaDataFromText(&$md, $removeMetaData = false) public function populateMetaDataFromText(&$md, $removeMetaData = false)
{ {
if ($md) { if (!$md) {
// get the text up to the first empty line return;
$extPattern = "/^(.+)\n\r*\n/Uis"; }
$matches = preg_match($extPattern, $md, $block);
if ($matches && $block[1]) { // See if there is YAML metadata block at the top of the document. e.g.
$metaDataFound = false; // ---
// property: value
// find the key/value pairs // another: value
$lines = preg_split('/\v+/', $block[1]); // ---
$key = ''; //
$value = ''; // If we found one, then we'll use a YAML parser to extract the
foreach ($lines as $line) { // data out and then remove the whole block from the markdown string.
if (strpos($line, ':') !== false) { $parser = new \Mni\FrontYAML\Parser();
list($key, $value) = explode(':', $line, 2); $document = $parser->parse($md, false);
$key = trim($key); $yaml = $document->getYAML();
$value = trim($value); if ($yaml) {
} else { foreach ($yaml as $key => $value) {
$value .= ' ' . trim($line); if (!property_exists(get_class($this), $key)) {
} continue;
if (property_exists(get_class(), $key)) {
$this->$key = $value;
$metaDataFound = true;
}
} }
$this->$key = $value;
}
if ($removeMetaData) {
$md = $document->getContent();
}
return;
}
// optionally remove the metadata block (only on the page that // this is the alternative way of parsing the properties out that don't contain
// is displayed) // a YAML block declared with ---
if ($metaDataFound && $removeMetaData) { //
$md = preg_replace($extPattern, '', $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]) {
$metaDataFound = false;
// 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);
} }
if (property_exists(get_class(), $key)) {
$this->$key = $value;
$metaDataFound = true;
}
}
// optionally remove the metadata block (only on the page that
// is displayed)
if ($metaDataFound && $removeMetaData) {
$md = preg_replace($extPattern, '', $md);
} }
} }
} }
@ -328,3 +350,4 @@ class DocumentationPage extends ViewableData
return sprintf(get_class($this) .': %s)', $this->getPath()); return sprintf(get_class($this) .': %s)', $this->getPath());
} }
} }

43
composer.json
View File

@ -1,24 +1,25 @@
{ {
"name": "silverstripe/docsviewer", "name": "silverstripe/docsviewer",
"description": "Documentation viewer module for SilverStripe", "description": "Documentation viewer module for SilverStripe",
"type": "silverstripe-module", "type": "silverstripe-module",
"keywords": ["silverstripe", "documentation"], "keywords": ["silverstripe", "documentation"],
"license": "BSD-3-Clause", "license": "BSD-3-Clause",
"authors": [{ "authors": [{
"name": "Will Rossiter", "name": "Will Rossiter",
"homepage": "http://wilr.github.io", "homepage": "http://wilr.github.io",
"email": "will@fullscreen.io" "email": "will@fullscreen.io"
}], }],
"support": { "support": {
"email": "will@fullscreen.io", "email": "will@fullscreen.io",
"irc": "irc://irc.freenode.org/silverstripe" "irc": "irc://irc.freenode.org/silverstripe"
}, },
"require": { "require": {
"silverstripe/framework": "~3.1", "silverstripe/framework": "~3.1",
"erusev/parsedown-extra": "0.2.2", "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" "suggest": {
} "silverstripe/staticpublisher": "Allows publishing documentation as HTML"
}
} }

38
tests/DocumentationParserTest.php
View File

@ -128,7 +128,6 @@ with multiple
lines lines
and tab indent and tab indent
and escaped < brackets and escaped < brackets
``` ```
Normal text after code block Normal text after code block
HTML; HTML;
@ -395,12 +394,39 @@ HTML;
public function testRetrieveMetaData() 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); $parsed = DocumentationParser::parse($this->metaDataPage);
$this->assertEquals("Foo Bar's Test page.", $this->metaDataPage->getTitle()); $expected = <<<HTML
$this->assertEquals("Foo Bar's Test page.", $this->metaDataPage->getTitle()); <h1 id="content">Content</h1>
$this->assertEquals("A long intro that splits over many lines", $this->metaDataPage->getIntroduction()); 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() public function testRewritingRelativeLinksToFiles()

7
tests/docs-parser/en/MetaDataTest.md
View File

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

13
tests/docs-parser/en/MetaDataYamlBlockTest.md Normal file
View File

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

1
tests/docs/en/test.md
View File

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