From 21e0ea7c21c87b442314be02a18c980097da8056 Mon Sep 17 00:00:00 2001
From: moshams272 <mohamedshamseldeen95@gmail.com>
Date: Mon, 30 Mar 2026 23:19:59 +0200
Subject: [PATCH 1/3] fix(metadata): ensure YAML frontmatter is captured when
 preceding first heading

---
 src/generators/metadata/utils/parse.mjs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/generators/metadata/utils/parse.mjs b/src/generators/metadata/utils/parse.mjs
index 7a3d98b2..29d3c333 100644
--- a/src/generators/metadata/utils/parse.mjs
+++ b/src/generators/metadata/utils/parse.mjs
@@ -102,8 +102,10 @@ export const parseApiDoc = ({ path, tree }, typeMap) => {
         ? tree.children.length
         : tree.children.indexOf(nextHeadingNode);
 
-    // Create subtree for this section
-    const subTree = createTree('root', tree.children.slice(index, stop));
+    // Create subtree for this section. If it's the first entry, we start from the
+    // beginning of the tree to ensure top-level nodes (like YAML) are captured.
+    const startIndex = metadataCollection.length === 0 ? 0 : index;
+    const subTree = createTree('root', tree.children.slice(startIndex, stop));
 
     visit(subTree, UNIST.isStabilityNode, node =>
       visitStability(node, ignoreStability ? undefined : metadata)

From 2e18282107d278afb70fb9646c023167cf415d64 Mon Sep 17 00:00:00 2001
From: moshams272 <mohamedshamseldeen95@gmail.com>
Date: Tue, 31 Mar 2026 10:02:46 +0200
Subject: [PATCH 2/3] feat(metadata): add tests for capturing YAML frontmatter

---
 .../metadata/utils/__tests__/parse.test.mjs   | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/src/generators/metadata/utils/__tests__/parse.test.mjs b/src/generators/metadata/utils/__tests__/parse.test.mjs
index ea653099..94f45d16 100644
--- a/src/generators/metadata/utils/__tests__/parse.test.mjs
+++ b/src/generators/metadata/utils/__tests__/parse.test.mjs
@@ -239,4 +239,40 @@ describe('parseApiDoc', () => {
       assert.strictEqual(results.length, 0);
     });
   });
+
+  describe('top-level nodes (YAML frontmatter)', () => {
+    it('captures top-level frontmatter in the first entry', () => {
+      const tree = u('root', [
+        u('yaml', 'layout: home\ncontributors: [shams]'),
+        h('First Heading'),
+        u('paragraph', [u('text', 'First content.')]),
+        h('Second Heading', 2),
+        u('paragraph', [u('text', 'Second content.')]),
+      ]);
+      const results = parseApiDoc({ path, tree }, typeMap);
+
+      assert.strictEqual(results.length, 2);
+
+      const firstContent = results[0].content.children;
+      assert.strictEqual(firstContent.length, 3);
+      assert.strictEqual(firstContent[0].type, 'yaml');
+      assert.strictEqual(firstContent[1].type, 'heading');
+
+      const secondContent = results[1].content.children;
+      assert.strictEqual(secondContent.length, 2);
+      assert.strictEqual(secondContent[0].type, 'heading');
+    });
+
+    it('works correctly without top-level frontmatter', () => {
+      const tree = u('root', [
+        h('First Heading'),
+        u('paragraph', [u('text', 'First content.')]),
+      ]);
+      const results = parseApiDoc({ path, tree }, typeMap);
+
+      assert.strictEqual(results.length, 1);
+      assert.strictEqual(results[0].content.children.length, 2);
+      assert.strictEqual(results[0].content.children[0].type, 'heading');
+    });
+  });
 });

From 49815a610e7457c592b2f679f7a3851fccb6ccee Mon Sep 17 00:00:00 2001
From: Mohamed Shams El-Deen <68347231+moshams272@users.noreply.github.com>
Date: Tue, 31 Mar 2026 16:11:53 +0200
Subject: [PATCH 3/3] test: remove redundant test

Removed test case for parsing without top-level frontmatter.
---
 .../metadata/utils/__tests__/parse.test.mjs          | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/src/generators/metadata/utils/__tests__/parse.test.mjs b/src/generators/metadata/utils/__tests__/parse.test.mjs
index 94f45d16..b7b9d2f6 100644
--- a/src/generators/metadata/utils/__tests__/parse.test.mjs
+++ b/src/generators/metadata/utils/__tests__/parse.test.mjs
@@ -262,17 +262,5 @@ describe('parseApiDoc', () => {
       assert.strictEqual(secondContent.length, 2);
       assert.strictEqual(secondContent[0].type, 'heading');
     });
-
-    it('works correctly without top-level frontmatter', () => {
-      const tree = u('root', [
-        h('First Heading'),
-        u('paragraph', [u('text', 'First content.')]),
-      ]);
-      const results = parseApiDoc({ path, tree }, typeMap);
-
-      assert.strictEqual(results.length, 1);
-      assert.strictEqual(results[0].content.children.length, 2);
-      assert.strictEqual(results[0].content.children[0].type, 'heading');
-    });
   });
 });