Merge pull request #1283 from harehare/feat/section-ops-examples

harehare · web-flow · commit d799ed9a0a90 · 2026-02-16T22:26:11.000+09:00
✨ feat(section): Add section operations and examples
diff --git a/crates/mq-lang/modules/section.mq b/crates/mq-lang/modules/section.mq
@@ -1,5 +1,10 @@
 def _is_section(section): is_dict(section) && section[:type] == :section;
 
+# Returns sections whose title contains the specified pattern.
+def section(md_nodes, pattern):
+  sections(md_nodes) | title_contains(pattern) | flatten()
+end
+
 # Splits markdown nodes into sections based on headers.
 def sections(md_nodes):
   if (is_empty(md_nodes)):
@@ -182,7 +187,14 @@ end
 
 # Flattens sections back to markdown nodes for output.
 # This converts section objects back to their original markdown node arrays.
+# Deprecated: use `flatten` instead.
 def collect(sections):
+  flatten(sections)
+end
+
+# Flattens sections back to markdown nodes for output.
+# This converts section objects back to their original markdown node arrays.
+def flatten(sections):
   if (is_empty(sections)):
     []
   else:
@@ -193,3 +205,4 @@ def collect(sections):
         section
     end)
 end
+
diff --git a/docs/books/src/start/example.md b/docs/books/src/start/example.md
@@ -209,6 +209,116 @@ $ mq 'sitemap(__FILE__, "https://example.com")' docs/**/*.md
 </url>
 ```
 
+## Section Operations
+
+### Extract Sections by Title
+
+Extract sections whose title contains a specific text:
+
+```mq
+include "section" | nodes | section("Installation")
+```
+
+**Input example**:
+
+```markdown
+# Introduction
+
+Welcome to the project.
+
+## Installation
+
+Run the following command:
+
+## Usage
+
+Use the tool like this.
+```
+
+**Output**: Returns the "Installation" section with its header and content.
+
+### Split Document by Header Level
+
+Split a document into sections based on header level:
+
+```mq
+include "section" | nodes | split(2)
+```
+
+**Input example**:
+
+```markdown
+# Main Title
+
+## Section 1
+
+Content of section 1.
+
+## Section 2
+
+Content of section 2.
+
+## Section 3
+
+Content of section 3.
+```
+
+**Output**: Returns an array of section objects split at `##` headers.
+
+### Generate Table of Contents from Sections
+
+Generate a table of contents from sections:
+
+```mq
+include "section" | nodes | sections() | toc()
+```
+
+**Input example**:
+
+```markdown
+# Introduction
+
+Some text.
+
+## Getting Started
+
+More text.
+
+### Prerequisites
+
+Details here.
+
+## Advanced Usage
+
+Advanced content.
+```
+
+**Output**: `["- Introduction", "  - Getting Started", "    - Prerequisites", "  - Advanced Usage"]`
+
+### Filter Sections with Content
+
+Filter sections that have content beyond the header:
+
+```mq
+include "section" | nodes | sections() | filter(fn(s): has_content(s);) | titles()
+```
+
+**Input example**:
+
+```markdown
+# Introduction
+
+Welcome to the project.
+
+## Empty Section
+
+## Usage
+
+Use the tool like this.
+```
+
+**Output**: `["Introduction", "Usage"]`
+
 ## Custom Functions and Programming
 
 ### Define Custom Function
diff --git a/docs/books/src/start/install.md b/docs/books/src/start/install.md
@@ -47,7 +47,7 @@ Invoke-WebRequest -Uri https://github.com/harehare/mq/releases/download/v0.5.15/
 
 ```sh
 # Using Homebrew (macOS and Linux)
-$ brew install harehare/tap/mq
+$ brew install mq
 ```
 
 ## Docker
diff --git a/packages/mq-playground/src/examples.ts b/packages/mq-playground/src/examples.ts
@@ -254,6 +254,91 @@ end
 - [Chapter2](Chapter2.md)
   - [Chapter3](Chapter3.md)
 - [Chapter4](Chapter4.md)
+`,
+        isUpdate: false,
+        format: "markdown",
+      },
+    ],
+  },
+  {
+    name: "Section Operations",
+    examples: [
+      {
+        name: "Extract section by title",
+        code: `include "section" | nodes | section("Installation")`,
+        markdown: `# Introduction
+
+Welcome to the project.
+
+## Installation
+
+Run the following command:
+
+\`\`\`bash
+npm install mq
+\`\`\`
+
+## Usage
+
+Use the tool like this.
+`,
+        isUpdate: false,
+        format: "markdown",
+      },
+      {
+        name: "Split by header level",
+        code: `include "section" | nodes | split(2) | titles()`,
+        markdown: `# Main Title
+
+## Section 1
+
+Content of section 1.
+
+## Section 2
+
+Content of section 2.
+
+## Section 3
+
+Content of section 3.
+`,
+        isUpdate: false,
+        format: "markdown",
+      },
+      {
+        name: "Table of contents",
+        code: `include "section" | nodes | sections() | toc()`,
+        markdown: `# Introduction
+
+Some text.
+
+## Getting Started
+
+More text.
+
+### Prerequisites
+
+Details here.
+
+## Advanced Usage
+
+Advanced content.
+`,
+        isUpdate: false,
+        format: "markdown",
+      },
+      {
+        name: "Filter sections with content",
+        code: `include "section" | nodes | sections() | filter(fn(s): has_content(s);) | titles()`,
+        markdown: `# Introduction
+
+Welcome to the project.
+
+## Empty Section
+
+## Usage
+
+Use the tool like this.
 `,
         isUpdate: false,
         format: "markdown",
