☯️ Markly::Merge
if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know on Discord or RubyForum, as I may have missed the notification.
if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️
I've summarized my thoughts in this blog post.
🌻 Synopsis 
markly-merge is a thin wrapper around markdown-merge that provides:
- **Hard dependency on Markly** - Ensures the libcmark-gfm (C) parser is installed
- **Markly-specific defaults** - Freeze token: `"markly-merge"`, `inner_merge_code_blocks: true`
- **Markly parse options** - Pass `flags:` and `extensions:` parameters
For an alternative using Comrak (Rust), see [commonmarker-merge][commonmarker-merge].
Features (via markdown-merge)
- **Markly-Powered**: Uses libcmark-gfm for accurate CommonMark + GFM parsing
- **Structure-Aware**: Understands headings, lists, code blocks, tables, and more
- **Intelligent**: Matches sections by heading structure and content signatures
- **Comment-Preserving**: HTML comments are preserved in context
- **Freeze Block Support**: Respects freeze markers (default: `markly-merge:freeze` / `markly-merge:unfreeze`) for merge control - customizable to match your project's conventions
- **Type Normalization**: Canonical node types work across all markdown backends
- **Full Provenance**: Tracks origin of every node
- **Inner-Merge Code Blocks**: Enabled by default - merges fenced code blocks using language-specific mergers
- **Customizable**:
- `signature_generator` - callable custom signature generators
- `preference` - setting of `:template`, `:destination`, or a Hash for per-node-type preferences
- `add_template_only_nodes` - setting to retain sections that do not exist in destination
- `freeze_token` - customize freeze block markers (default: `"markly-merge"`)
- `flags` - Markly parse flags (e.g., `Markly::FOOTNOTES`, `Markly::SMART`)
- `extensions` - GFM extensions (`:table`, `:strikethrough`, `:autolink`, `:tagfilter`, `:tasklist`)
Removal Mode Scope
remove_template_missing_nodes: true in markly-merge follows the shared markdown-merge full-document contract:
- removes top-level destination-only structural blocks
- preserves standalone HTML comment-only fragments, link reference definitions, and freeze blocks
- preserves one separator blank line when removed structural content collapses around a kept standalone HTML comment fragment
- does not yet define generic inline-comment promotion or recursive/nested section-removal semantics
Section-local replace_mode / partial-template behavior still follows its own conservative Markdown rules and should not be assumed to inherit the same recursive removal contract as full-document smart merge.
Supported Node Types
| Node Type | Signature Format | Matching Behavior |
|---|---|---|
| Heading | [:heading, level, text] |
Headings match by level and text content |
| Paragraph | [:paragraph, text_hash] |
Paragraphs match by content hash |
| List | [:list, type, item_count] |
Lists match by type (bullet/ordered) and structure |
| List Item | [:list_item, content_sig] |
Items match by content signature |
| Code Block | [:code_block, language, info] |
Code blocks match by language and info string |
| Block Quote | [:block_quote, content_sig] |
Block quotes match by content signature |
| Table | [:table, header_sig] |
Tables match by header structure |
| HTML Block | [:html_block, content] |
HTML blocks match by content |
| Thematic Break | [:thematic_break] |
Horizontal rules always match |
Example
require "markly/merge"
template = File.read("template.md")
destination = File.read("destination.md")
merger = Markly::Merge::SmartMerger.new(template, destination)
result = merger.merge
File.write("merged.md", result.to_markdown)
💡 Info you can shake a stick at
| Tokens to Remember |   |
|---|---|
| Works with MRI Ruby 4 |  |
| Support & Community |      |
| Source |     |
| Documentation |      |
| Compliance |      |
| Style |     |
| Maintainer 🎖️ |      |
... 💖 |
    🧊 🐙 🛖 🧪 |
Compatibility
Compatible with MRI Ruby 4.0.0+, and concordant releases of JRuby, and TruffleRuby.
CI workflows and Appraisals are generated for MRI Ruby 4.0.0+.
This test floor is configured by ruby.test_minimum in .kettle-jem.yml and
may be higher than the gem's runtime compatibility floor when legacy Rubies are
not practical for the current toolchain.
The amazing test matrix is powered by the kettle-dev stack.
How kettle-dev manages complexity in tests
| Gem | Source | Role | Total downloads |
|---|---|---|---|
| appraisal2 | GitHub | multi-dependency Appraisal matrix generation |  |
| appraisal2-rubocop | GitHub | RuboCop Appraisal generator integration |  |
| kettle-dev | GitHub | development, release, and CI workflow tooling |  |
| kettle-jem | GitHub | Appraisals & CI workflow templates |  |
| kettle-soup-cover | GitHub | SimpleCov coverage policy and reporting |  |
| kettle-test | GitHub | standard test runner and coverage harness |  |
| rubocop-lts | GitHub | Ruby-version-aware linting |  |
| turbo_tests2 | GitHub | parallel test execution |  |
✨ Installation
Install the gem and add to the application's Gemfile by executing:
bundle add markly-merge
If bundler is not being used to manage dependencies, install the gem by executing:
gem install markly-merge
⚙️ Configuration
merger = Markly::Merge::SmartMerger.new(
template_content,
dest_content,
# Which version to prefer when nodes match
# :destination (default) - keep destination content
# :template - use template content
preference: :destination,
# Whether to add template-only nodes to the result
# false (default) - only include sections that exist in destination
# true - include all template sections
add_template_only_nodes: false,
# Token for freeze block markers
# Default: "markly-merge"
# Looks for: <!-- markly-merge:freeze --> / <!-- markly-merge:unfreeze -->
freeze_token: "markly-merge",
# Custom signature generator (optional)
# Receives a node, returns a signature array or nil
signature_generator: ->(node) { [:heading, node.header_level, node.string_content] if node.type == :heading },
)
🔧 Basic Usage
Simple Merge
require "markly/merge"
# Template defines the structure
template = <<~MD
# My Project
## How to Install
Run `gem install my-project`.
## How to Use
Instructions here.
## Contributing
Please read CONTRIBUTING.md.
MD
# Destination has customizations
destination = <<~MD
# My Project
## How to Install
Use bundler for better dependency management:
```bash
bundle add my-project
```
## Custom Section
This section only exists in destination.
MD
merger = Markly::Merge::SmartMerger.new(template, destination)
result = merger.merge
puts result.to_markdown
Using Freeze Blocks
Freeze blocks protect sections from being overwritten during merge:
# My Project
## How to Install
<!-- markly-merge:freeze Custom install instructions -->
This installation section has been customized and will be preserved
during template merges, regardless of what the template contains.
<!-- markly-merge:unfreeze -->
## How to Use
Standard usage section from template.
Content between <!-- markly-merge:freeze --> and <!-- markly-merge:unfreeze --> markers is preserved from the destination file.
Adding Template-Only Sections
merger = Markly::Merge::SmartMerger.new(
template,
destination,
add_template_only_nodes: true,
)
result = merger.merge
# Result includes sections from template that don't exist in destination
Freeze Blocks
Freeze blocks protect sections from being modified during merges. They are marked with HTML comments that are invisible when the Markdown is rendered:
<!-- markdown-merge:freeze -->
# Some Markdown in here!
<!-- markdown-merge:unfreeze -->
🔐 Security
See SECURITY.md.
🤝 Contributing
If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check issues or PRs, or use the gem and think about how it could be better.
We so if you make changes, remember to update it.
See CONTRIBUTING.md for more detailed instructions.
Code Coverage
Coverage service badges
📌 Versioning
This library follows for its public API where practical.
For most applications, prefer the Pessimistic Version Constraint with two digits of precision.
For example:
spec.add_dependency("markly-merge", "~> 7.0")
📌 Is "Platform Support" part of the public API? More details inside.
Dropping support for a platform can be a breaking change for affected users. If a release changes supported platforms, it should be called out clearly in the changelog and versioned with that impact in mind.
To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:
See CHANGELOG.md for a list of releases.
📄 License
The gem is available under the following licenses: AGPL-3.0-only, PolyForm-Small-Business-1.0.0. See LICENSE.md for details.
If none of the available licenses suit your use case, please contact us to discuss a custom commercial license.