From a301eaae39a3564e61085380e9e0a1cdd31b26d1 Mon Sep 17 00:00:00 2001
From: harehare <harehare1110@gmail.com>
Date: Wed, 4 Mar 2026 21:31:18 +0900
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat:=20add=20frontmatter=20extract?=
 =?UTF-8?q?ion=20examples=20and=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1359
---
 README.md                              |  3 +++
 docs/books/src/start/example.md        | 10 ++++++++++
 editors/vscode/src/extension.ts        |  3 +++
 packages/mq-playground/src/examples.ts | 17 +++++++++++++++++
 4 files changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 026c1ac72..5cf420e9d 100644
--- a/README.md
+++ b/README.md
@@ -329,6 +329,9 @@ mq 'select(.h1 || .h2)' example.html
 
 # Extract specific cell from a Markdown table
 mq '.[1][2] | to_text()' data.md
+
+# Extract frontmatter metadata from markdown files:
+import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)
 ```
 
 ### Using with markitdown
diff --git a/docs/books/src/start/example.md b/docs/books/src/start/example.md
index 98fdaa2b9..38a9fb9ea 100644
--- a/docs/books/src/start/example.md
+++ b/docs/books/src/start/example.md
@@ -461,3 +461,13 @@ $ mq -A 'let headers = count_by(fn(x): x | select(.h);)
 | let anchor = downcase(replace(text, " ", "-"))
 | if (!is_empty(text)): s"${indent}- [${text}](#${anchor})"
 ```
+
+## Frontmatter Operations
+
+Extract frontmatter metadata from markdown files:
+
+```mq
+import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)
+```
+
+
diff --git a/editors/vscode/src/extension.ts b/editors/vscode/src/extension.ts
index a108d706e..802ac124f 100644
--- a/editors/vscode/src/extension.ts
+++ b/editors/vscode/src/extension.ts
@@ -39,6 +39,9 @@ def snake_to_camel(x):
 
 # CSV parse
 include "csv" | csv_parse("a,b,c\n1,2,3\n4,5,6", true) | csv_to_markdown_table()
+
+# Extract Front Matter
+import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)
 `;
 
 let client: lc.LanguageClient | null = null;
diff --git a/packages/mq-playground/src/examples.ts b/packages/mq-playground/src/examples.ts
index c39888cb8..1c69d07f9 100644
--- a/packages/mq-playground/src/examples.ts
+++ b/packages/mq-playground/src/examples.ts
@@ -254,6 +254,23 @@ end
 - [Chapter2](Chapter2.md)
   - [Chapter3](Chapter3.md)
 - [Chapter4](Chapter4.md)
+`,
+        isUpdate: false,
+        format: "markdown",
+      },
+      {
+        name: "Extract frontmatter data",
+        code: `import "yaml" | if (.yaml): yaml::yaml_parse() | get(:title)`,
+        markdown: `---
+title: "Sample Document"
+author: "John Doe"
+date: "2024-01-01"
+---
+
+# Sample Document
+
+This is a sample document with frontmatter.
+
 `,
         isUpdate: false,
         format: "markdown",