Merge pull request #875 from patchlevel/format-docs

Add frontmatter support for docs formatting, format docs

Author: DanielBadura

bin/docs-extract-php-code

@@ -3,6 +3,8 @@
 
 use League\CommonMark\Environment\Environment;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Extension\FrontMatter\Data\FrontMatterDataParserInterface;
+use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
 use League\CommonMark\Node\Query;
 use League\CommonMark\Parser\MarkdownParser;
 use Wnx\CommonmarkMarkdownRenderer\MarkdownRendererExtension;
@@ -11,6 +13,15 @@ require __DIR__ . '/../vendor/autoload.php';
 
 $environment = new Environment([]);
 $environment->addExtension(new MarkdownRendererExtension());
+$environment->addExtension(new FrontMatterExtension(
+    // keep the raw YAML string so it round-trips byte-identically
+    new class implements FrontMatterDataParserInterface {
+        public function parse(string $frontMatter): string
+        {
+            return $frontMatter;
+        }
+    },
+));
 
 $parser = new MarkdownParser($environment);
 

bin/docs-inject-php-code

@@ -3,6 +3,9 @@
 
 use League\CommonMark\Environment\Environment;
 use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Extension\FrontMatter\Data\FrontMatterDataParserInterface;
+use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
+use League\CommonMark\Extension\FrontMatter\Output\RenderedContentWithFrontMatter;
 use League\CommonMark\Node\Query;
 use League\CommonMark\Parser\MarkdownParser;
 use Wnx\CommonmarkMarkdownRenderer\MarkdownRendererExtension;
@@ -14,6 +17,15 @@ require __DIR__ . '/../vendor/autoload.php';
 
 $environment = new Environment([]);
 $environment->addExtension(new MarkdownRendererExtension());
+$environment->addExtension(new FrontMatterExtension(
+    // keep the raw YAML string so it round-trips byte-identically
+    new class implements FrontMatterDataParserInterface {
+        public function parse(string $frontMatter): string
+        {
+            return $frontMatter;
+        }
+    },
+));
 
 $parser = new MarkdownParser($environment);
 $markdownRenderer = new MarkdownRenderer($environment);
@@ -62,7 +74,14 @@ foreach ($finder as $file) {
         $node->setLiteral(trim($code));
     }
 
-    file_put_contents($file->getPathname(), $markdownRenderer->renderDocument($document));
+    $rendered = $markdownRenderer->renderDocument($document);
+    $output = $rendered->getContent();
+
+    if ($rendered instanceof RenderedContentWithFrontMatter) {
+        $output = $rendered->getFrontMatter() . "---\n" . $output;
+    }
+
+    file_put_contents($file->getPathname(), $output);
 }
 
 if (file_exists($targetDir)) {

docs/message.md

@@ -97,7 +97,6 @@ use Patchlevel\EventSourcing\Message\Message;
 /** @var Message $message */
 $message->header(ApplicationHeader::class);
 ```
-
 ## Missing headers
 
 When a message is deserialized, every header name is resolved to its registered header class.
@@ -117,7 +116,6 @@ $serializer = DefaultHeadersSerializer::createFromPaths(
     ['legacyApplication', 'legacyTenant'],
 );
 ```
-
 You can access the collected headers via the `MissingHeaders` object:
 
 ```php
@@ -127,7 +125,6 @@ use Patchlevel\EventSourcing\Message\MissingHeaders;
 $missingHeaders = $message->header(MissingHeaders::class);
 $missingHeaders->headers; // ['legacyApplication' => [...], 'legacyTenant' => [...]]
 ```
-
 :::warning
 Only the header names you list are handled gracefully. If a message contains an unregistered header
 whose name is **not** in the list, deserialization still throws `HeaderNameNotRegistered`.
@@ -143,7 +140,6 @@ $serializer = DefaultHeadersSerializer::createFromPaths(
     ['*'],
 );
 ```
-
 ## Pipe
 
 The `Pipe` is a construct that allows you to chain multiple translators.