From b4f5c0467fbb3ddb0cdfb5066cd10ed27fb70415 Mon Sep 17 00:00:00 2001
From: David Badura <david.badura@patchlevel.de>
Date: Sun, 18 Oct 2026 19:36:15 +0200
Subject: [PATCH 1/2] Fix the file name of the 2.0 upgrade guide in the
 navigation

---
 docs/project.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/project.json b/docs/project.json
index 66455feb..3effe9bc 100644
--- a/docs/project.json
+++ b/docs/project.json
@@ -25,7 +25,7 @@
     {
       "title": "Miscellaneous",
       "subEntries": [
-        { "title": "Upgrade from 1.x", "file": "UPGRADE-2.0md" }
+        { "title": "Upgrade from 1.x", "file": "UPGRADE-2.0.md" }
       ]
     }
   ]

From f73f4ecd7f8c59820c250c81d7f16ed54bd2200a Mon Sep 17 00:00:00 2001
From: David Badura <david.badura@patchlevel.de>
Date: Sun, 18 Oct 2026 19:36:43 +0200
Subject: [PATCH 2/2] Keep the frontmatter of the docs when formatting the code

The docs scripts parse the pages with CommonMark, which rendered the
frontmatter as a thematic break and a heading. They use the FrontMatterExtension
now, the same way as the scripts of the event-sourcing repository.
---
 bin/docs-extract-php-code | 11 +++++++++++
 bin/docs-inject-php-code  | 21 ++++++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/bin/docs-extract-php-code b/bin/docs-extract-php-code
index d50b642d..a27094df 100755
--- a/bin/docs-extract-php-code
+++ b/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);
 
diff --git a/bin/docs-inject-php-code b/bin/docs-inject-php-code
index e4e81ead..13694a10 100755
--- a/bin/docs-inject-php-code
+++ b/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)) {