markdown_composer 0.7.0

data/docs/examples/md_composer_example_basic_compose.md

@@ -0,0 +1,57 @@
+---
+title: Markdown Composer Basic Compose Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Basic example for selecting one section from a Markdown source.
+---
+
+# Markdown Composer Basic Compose Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Compose anatomy | [../compose/md_composer_compose_anatomy.md](../compose/md_composer_compose_anatomy.md) |
+| Select | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+
+---
+
+## 1. Goal
+
+Select the `Overview` section from the shared current fixture and make it the whole output.
+
+## 2. Input
+
+Use [../../examples/fixtures/current.md](../../examples/fixtures/current.md).
+
+## 3. Config
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+plan = MarkdownComposer.plan do
+  from :current
+  select 'heading_2_section where title:equals("Overview")'
+  include "all"
+  set
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+## 4. Expected Output
+
+```markdown
+## Overview
+
+This overview section is the normal starting point for Markdown Composer examples.
+```
+
+## 5. Why It Works
+
+`heading_2_section` selects the heading and body. `where title:equals("Overview")` filters to the desired section. `set` replaces the buffer with that selected content.
+
+Runnable version: [../../examples/basic_compose.rb](../../examples/basic_compose.rb).

data/docs/examples/md_composer_example_buffer_target_actions.md

@@ -0,0 +1,83 @@
+---
+title: Markdown Composer Buffer Target Actions Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for remove_buffer_target and transform_buffer_target.
+---
+
+# Markdown Composer Buffer Target Actions Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Actions | [../compose/md_composer_compose_actions.md](../compose/md_composer_compose_actions.md) |
+| Targets | [../compose/md_composer_compose_targets.md](../compose/md_composer_compose_targets.md) |
+
+---
+
+## 1. Goal
+
+Create a buffer from shared fixtures, remove one temporary section, then transform existing buffer headings.
+
+## 2. Config
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+  inherited :site_intro, File.read("examples/fixtures/site_intro.md")
+end
+
+plan = MarkdownComposer.plan do
+  from :current
+  select 'heading_2_section where title:equals("Feature Matrix")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  set
+
+  from({ type: "inherited", key: "site_intro" })
+  select 'heading_2_section where title:equals("Welcome")'
+  include "all"
+  append
+
+  from({
+    type: "inline",
+    markdown: "## Cleanup Marker\n\nRemove this temporary section."
+  })
+  select "heading_2_section"
+  include "all"
+  append
+
+  from :buffer
+  select 'heading_2_section where title:equals("Cleanup Marker")'
+  remove_buffer_target
+
+  transform_buffer_target(
+    'heading_2 where title:equals("Welcome")',
+    transforms: [
+      { "transform" => "heading_levels", "mode" => "demote", "options" => { "by" => 1 } }
+    ]
+  )
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+## 3. Expected Output
+
+```markdown
+## Feature Matrix
+
+The table below is intended for table selection and table-row experiments.
+
+### Welcome
+
+This inherited introduction can be prepended to composed output.
+```
+
+## 4. Why It Works
+
+`remove_buffer_target` and `transform_buffer_target` use `target` as the meaningful address. The selected source content is not inserted into the buffer by those actions.
+
+Runnable versions: [../../examples/advanced_composer.rb](../../examples/advanced_composer.rb) and [../../examples/complex_composer.rb](../../examples/complex_composer.rb).

data/docs/examples/md_composer_example_fixtures.md

@@ -0,0 +1,62 @@
+---
+title: Markdown Composer Example Fixtures
+type: examples
+status: current
+updated: 2026-06-07
+description: Map of the shared Markdown and HTML fixtures used by runnable Markdown Composer examples.
+---
+
+# Markdown Composer Example Fixtures
+
+### References
+
+| What | Where |
+|------|-------|
+| Runnable examples | [./md_composer_runnable_examples.md](./md_composer_runnable_examples.md) |
+| Source guide | [../compose/md_composer_compose_sources.md](../compose/md_composer_compose_sources.md) |
+| Include guide | [../compose/md_composer_compose_include.md](../compose/md_composer_compose_include.md) |
+
+---
+
+## 1. Fixture Directory
+
+User-facing example fixtures live in [../../examples/fixtures](../../examples/fixtures). They are separate from `test/fixtures`, which are larger automated-test inputs.
+
+## 2. Fixture Map
+
+| Fixture | Source role | Useful sections |
+|---------|-------------|-----------------|
+| [current.md](../../examples/fixtures/current.md) | Main `current` source. | `Overview`, `Feature Matrix`, `Operations`, `Diagrams And Math`, `Draft Notes`, `Appendix`. |
+| [guide.md](../../examples/fixtures/guide.md) | Keyed `explicit :guide` source. | `Install`, `Configure`, `Validate`, `Publish`. |
+| [faq.md](../../examples/fixtures/faq.md) | Keyed `explicit :faq` source. | `Can I use this outside Rails?`, `Can plans be YAML?`, `What source types exist?`, `Can I transform output?`. |
+| [site_intro.md](../../examples/fixtures/site_intro.md) | Keyed `inherited :site_intro` source. | `Welcome`, `Navigation`, inherited audience/context text. |
+| [source.html](../../examples/fixtures/source.html) | HTML source fixture. | HTML `Overview` content for best-effort HTML-to-Markdown examples. |
+
+## 3. Notable Current Source Sections
+
+`current.md` is intentionally broad:
+
+- `Feature Matrix` includes a first paragraph, link, table, H3 sections, fenced code, and nested H4 content.
+- `Operations` includes runbook-style sections, ordered steps, fenced shell code, and monitoring content.
+- `Diagrams And Math` includes Mermaid and math examples.
+- `Appendix` includes source-type and copy-paste checklist material.
+
+## 4. Loading Fixtures
+
+Use the source list DSL in runnable Ruby examples:
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+  explicit :guide, File.read("examples/fixtures/guide.md")
+  explicit :faq, File.read("examples/fixtures/faq.md")
+  inherited :site_intro, File.read("examples/fixtures/site_intro.md")
+end
+```
+
+The `key` in `explicit :guide` or `inherited :site_intro` is the key used by compose rows such as:
+
+```ruby
+from({ type: "explicit", key: "guide" })
+from({ type: "inherited", key: "site_intro" })
+```

data/docs/examples/md_composer_example_html_output.md

@@ -0,0 +1,50 @@
+---
+title: Markdown Composer HTML Output Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for rendering Markdown Composer output as HTML.
+---
+
+# Markdown Composer HTML Output Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform modes | [../transform/md_composer_transform_modes.md](../transform/md_composer_transform_modes.md) |
+| API reference | [../reference/md_composer_reference_api.md](../reference/md_composer_reference_api.md) |
+
+---
+
+## 1. Goal
+
+Render selected Markdown to HTML and add link attributes to external links.
+
+## 2. Config
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current html: File.read("examples/fixtures/source.html"), preferred_format: :html
+end
+
+config = {
+  "compose" => [
+    { "select" => "all", "action" => "set" }
+  ],
+  "transform" => [
+    { "scope" => "output", "transform" => "links", "mode" => "nofollow" },
+    { "scope" => "output", "transform" => "links", "mode" => "target_blank" }
+  ],
+  "output" => "html"
+}
+
+result = MarkdownComposer.compose(sources: sources, config: config)
+puts result.html
+```
+
+## 3. Important Caveat
+
+HTML link attribute modes are top-level HTML-output post-processing. They apply to rendered external links and skip empty links and internal `#anchor` links. Row-level link attribute transforms do not update final HTML attributes.
+
+For Markdown output from the HTML fixture, see [../../examples/html_input.rb](../../examples/html_input.rb).

data/docs/examples/md_composer_example_modify.md

@@ -0,0 +1,77 @@
+---
+title: Markdown Composer Modify Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for using the modify action to transform selected source content while composing.
+---
+
+# Markdown Composer Modify Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Actions | [../compose/md_composer_compose_actions.md](../compose/md_composer_compose_actions.md) |
+| Transform anatomy | [../transform/md_composer_transform_anatomy.md](../transform/md_composer_transform_anatomy.md) |
+
+---
+
+## 1. Goal
+
+Select a section from the shared current fixture, transform selected content while composing, and append the transformed fragment.
+
+## 2. Config
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+plan = MarkdownComposer.plan do
+  from :current
+  select 'heading_2_section where title:equals("Feature Matrix")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  set
+
+  from :current
+  select 'heading_3_section where title:equals("Dashboard")'
+  include "all"
+  modify "end", transforms: [
+    {
+      "scope" => "heading_3, paragraph",
+      "transform" => "replace_text",
+      "mode" => "literal",
+      "options" => {
+        "from" => "Dashboard",
+        "to" => "Dashboard Snapshot"
+      }
+    }
+  ]
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+## 3. Expected Output
+
+```markdown
+## Feature Matrix
+
+The table below is intended for table selection and table-row experiments.
+
+### Dashboard Snapshot
+
+Dashboard Snapshot cards should keep this heading and paragraph when selected.
+```
+
+## 4. Why It Works
+
+`modify` creates a temporary fragment from selected source content, runs nested transforms against that fragment, then places the transformed fragment at the target.
+
+## 5. Variation: In Place
+
+To rewrite existing buffer content inline, use a later row with `source: "buffer"` and `target: "in_place"`.
+
+Runnable versions: [../../examples/advanced_composer.rb](../../examples/advanced_composer.rb) and [../../examples/complex_composer.rb](../../examples/complex_composer.rb).

data/docs/examples/md_composer_example_multi_row_compose.md

@@ -0,0 +1,67 @@
+---
+title: Markdown Composer Multi-Row Compose Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for building output from multiple compose rows.
+---
+
+# Markdown Composer Multi-Row Compose Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Compose anatomy | [../compose/md_composer_compose_anatomy.md](../compose/md_composer_compose_anatomy.md) |
+| Buffer | [../compose/md_composer_compose_buffer.md](../compose/md_composer_compose_buffer.md) |
+
+---
+
+## 1. Goal
+
+Build a new document from multiple sections in the shared current fixture and remove draft-only content from the buffer.
+
+## 2. Config
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+plan = MarkdownComposer.plan do
+  from :current
+  select 'heading_2_section where title:equals("Overview")'
+  include "all"
+  set
+
+  from :current
+  select 'heading_2_section where title:equals("Feature Matrix")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  append
+
+  from :buffer
+  select 'paragraph where text:contains("draft")'
+  remove_buffer_target
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+## 3. Expected Output
+
+```markdown
+## Overview
+
+This overview section is the normal starting point for Markdown Composer examples.
+
+## Feature Matrix
+
+The table below is intended for table selection and table-row experiments.
+```
+
+## 4. Why It Works
+
+The first row creates the buffer. The second appends another section. The third uses `source: "buffer"` and a target selector to remove the draft paragraph from composed output.
+
+Runnable versions: [../../examples/source_list_dsl.rb](../../examples/source_list_dsl.rb) and [../../examples/standard_sources_buffer.rb](../../examples/standard_sources_buffer.rb).

data/docs/examples/md_composer_example_ruby_plans.md

@@ -0,0 +1,62 @@
+---
+title: Markdown Composer Ruby Plans Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for authoring Markdown Composer plans with Ruby DSL and structured hashes.
+---
+
+# Markdown Composer Ruby Plans Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Plan schema | [../reference/md_composer_reference_plan_schema.md](../reference/md_composer_reference_plan_schema.md) |
+| API reference | [../reference/md_composer_reference_api.md](../reference/md_composer_reference_api.md) |
+
+---
+
+## 1. Block DSL
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+plan = MarkdownComposer.plan do
+  from :current
+  select 'heading_2_section where title:equals("Overview")'
+  include "all"
+  set
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+Use the DSL for hand-authored Ruby code and tests.
+
+## 2. Structured Hash
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+config = {
+  "compose" => [
+    {
+      "source" => "current",
+      "select" => 'heading_2_section where title:equals("Overview")',
+      "include" => "all",
+      "action" => "set"
+    }
+  ]
+}
+
+result = MarkdownComposer.compose(sources: sources, config: config)
+```
+
+Use structured hashes for storage, APIs, GUI builders, YAML, JSON, and row import/export.
+
+For source-list syntax, see [Source Ruby DSL](./md_composer_source_ruby_dsl.md). Runnable versions: [../../examples/basic_compose.rb](../../examples/basic_compose.rb) and [../../examples/source_list_dsl.rb](../../examples/source_list_dsl.rb).

data/docs/examples/md_composer_example_structured_data.md

@@ -0,0 +1,68 @@
+---
+title: Markdown Composer Structured Data Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for selecting YAML or JSON data blocks and extracting values with data_path.
+---
+
+# Markdown Composer Structured Data Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Include | [../compose/md_composer_compose_include.md](../compose/md_composer_compose_include.md) |
+| Targets | [../compose/md_composer_compose_targets.md](../compose/md_composer_compose_targets.md) |
+
+---
+
+## 1. Goal
+
+Extract selected values from a YAML data block.
+
+The shared fixtures focus on Markdown, HTML, tables, code, Mermaid, math, and source composition. This structured-data example stays self-contained because the fixture set does not include a YAML data block.
+
+## 2. Input
+
+````markdown
+```yaml
+fields:
+  - type: dropdown
+    label: Plan
+  - type: text
+    label: Name
+```
+````
+
+## 3. Config
+
+```ruby
+sources = [
+  {
+    "key" => "current",
+    "type" => "current",
+    "markdown" => "```yaml\nfields:\n  - type: dropdown\n    label: Plan\n  - type: text\n    label: Name\n```\n"
+  }
+]
+
+config = {
+  "compose" => [
+    {
+      "select" => "data_block where format:equals(\"yaml\")",
+      "include" => "data_path(\"fields[type=dropdown].label\")",
+      "action" => "set"
+    }
+  ]
+}
+```
+
+## 4. Expected Output
+
+```markdown
+Plan
+```
+
+## 5. Data Record And Data Value Note
+
+`data_path(...)` creates transient derived nodes called `data_record` or `data_value` depending on the extracted value. In ordinary Markdown output they serialize to Markdown text, so target the serialized text unless a host adapter preserves structured nodes.

data/docs/examples/md_composer_example_transforms.md

@@ -0,0 +1,68 @@
+---
+title: Markdown Composer Transform Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for top-level transform rows.
+---
+
+# Markdown Composer Transform Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform anatomy | [../transform/md_composer_transform_anatomy.md](../transform/md_composer_transform_anatomy.md) |
+| Options | [../transform/md_composer_transform_options.md](../transform/md_composer_transform_options.md) |
+
+---
+
+## 1. Goal
+
+Compose selected sections from the shared current fixture, rename a heading, promote heading levels, and insert a generated Summary section.
+
+## 2. Config
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+plan = MarkdownComposer.plan do
+  from :current
+  select 'h2_section where title:equals("Feature Matrix")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  set
+
+  transform "heading_2", "replace_text", "literal", {
+    "from" => "Feature Matrix",
+    "to" => "Feature Matrix Summary"
+  }
+
+  transform "heading", "heading_levels", "promote", {
+    "by" => 1
+  }
+
+  transform "paragraph[first:1]", "insert_after", "insert", {
+    "content" => "\n## Summary\n\nGenerated summary text.",
+    "as" => "paragraph"
+  }
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+## 3. Expected Output
+
+```markdown
+# Feature Matrix Summary
+
+The table below is intended for table selection and table-row experiments.
+
+## Summary
+
+Generated summary text.
+```
+
+Runnable versions: [../../examples/standard_composer.rb](../../examples/standard_composer.rb) and [../../examples/complex_composer.rb](../../examples/complex_composer.rb).

data/docs/examples/md_composer_example_yaml_json_rows.md

@@ -0,0 +1,56 @@
+---
+title: Markdown Composer YAML JSON Rows Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for YAML, JSON, and row import/export with Markdown Composer.
+---
+
+# Markdown Composer YAML JSON Rows Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Plan schema | [../reference/md_composer_reference_plan_schema.md](../reference/md_composer_reference_plan_schema.md) |
+| Diagnostics | [../reference/md_composer_reference_diagnostics.md](../reference/md_composer_reference_diagnostics.md) |
+
+---
+
+## 1. YAML Config
+
+```yaml
+output: markdown
+compose:
+  - source: current
+    select: heading_2_section where title:equals("Overview")
+    include: all
+    action: set
+```
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+end
+
+config = MarkdownComposer.parse_yaml(yaml_string)
+result = MarkdownComposer.compose(sources: sources, config: config)
+```
+
+## 2. JSON Config
+
+```ruby
+json = MarkdownComposer.to_json(config)
+config = MarkdownComposer.parse_json(json)
+```
+
+## 3. Rows
+
+```ruby
+rows = MarkdownComposer.to_rows(MarkdownComposer::Plan.new(config))
+plan = MarkdownComposer.parse_rows(rows)
+```
+
+Rows are useful for table-like UIs and import/export workflows.
+
+Runnable version: [../../examples/yaml_plan.rb](../../examples/yaml_plan.rb). YAML file: [../../examples/plans/basic.yml](../../examples/plans/basic.yml).