md-scatter

A tool to help teams collaborate on markdown files via git. It splits a markdown file into separate sections that can be worked on in parallel without merge conflicts. Once collaboration is complete, the tool reassembles the sections into a single file.

Installation

Install via Cargo:

cargo install md-scatter

How It Works

Scattering

Mark sections you want to split using the $scatter token. For example:

Before

# Main Document

## Introduction

$scatter

## Features

$scatter

After running md-scatter scatter input.md:

The original file is updated with links to the scattered sections:

# Main Document

## Introduction
[View section](input/introduction.md)

## Features
[View section](input/features.md)

And two new files are created in the input/ subdirectory:

• input/introduction.md: contains the Introduction section content
• input/features.md: contains the Features section content

Regrouping

Once collaboration is complete, run md-scatter regroup input.md to merge the scattered sections back into the main document. The tool reads the linked files from the input/ subdirectory and replaces the links with the actual content from those files, restoring the original structure.

CLI

Usage

Scatter

# Scatter sections which contain a $scatter token
md-scatter scatter input.md

# Scatter H2 headers
md-scatter scatter input.md --level 2

# Dry run - copy to temp, print path, run scatter
md-scatter scatter input.md --dry-run

Regroup

# Regroup sections from linked files back into the main document
md-scatter regroup input.md

# Regroup all linked sections (not just those in the markdown file's subfolder)
md-scatter regroup input.md --all

# Dry run - copy to temp, print path, run regroup
md-scatter regroup input.md --dry-run