markmv ✏️

npx markmv --help

TypeScript CLI for markdown file operations with intelligent link refactoring

markmv revolutionises how you manage markdown documentation by providing intelligent file operations that automatically maintain link integrity across your entire project. Whether you're reorganising documentation, splitting large files, or combining related content, markmv ensures your links never break.

✨ Key Features

• 🚀 Move files/directories with automatic link updates
• ✂️ Split large files by headers, size, or manual markers
• 🔗 Join multiple files with conflict resolution
• 🧠 Merge content with interactive conflict handling
• 📚 Generate indexes for documentation organization
• 🌐 Multiple access methods: CLI, REST API, MCP, and programmatic

📦 Installation

# Use directly with npx (recommended)
npx markmv --help

# Install globally
npm install -g markmv

# Install as library
npm install markmv

Requirements: Node.js >= 18.0.0

🚀 Quick Start

# Move a file and update all references
npx markmv move old-doc.md new-location/renamed-doc.md

# Split a large file by headers
npx markmv split large-guide.md --strategy headers --header-level 2

# Join multiple files
npx markmv join intro.md setup.md usage.md --output complete-guide.md

# Generate documentation index
npx markmv index --type links --strategy directory

🌐 Access Methods

markmv provides multiple interfaces for different use cases:

CLI Tool

npx markmv move old.md new.md --json  # JSON output for scripting

REST API Server

npx --package=markmv markmv-api  # Start HTTP server on port 3000

MCP Server (AI Integration)

npx --package=markmv markmv-mcp  # Model Context Protocol server

Programmatic API

import { moveFile } from 'markmv';
const result = await moveFile('old.md', 'new.md');

🤖 MCP Setup (AI Integration)

The markmv MCP server enables AI agents (like Claude) to use markmv functionality directly. Here's how to set it up:

Claude Desktop Configuration

Add markmv to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "markmv": {
      "command": "npx",
      "args": [
        "--package=markmv",
        "markmv-mcp"
      ],
      "env": {
        "NODE_OPTIONS": "--no-warnings"
      }
    }
  }
}

Available MCP Tools

Once configured, Claude can use these markmv tools:

• move_file - Move/rename files with link updates
• move_files - Move multiple files in batch
• validate_operation - Check for broken links

Note: Additional tools (split, join, merge, convert, index) will be added in future releases.

Example Usage with Claude

After setup, you can ask Claude to:

"Use markmv to move docs/old-guide.md to guides/new-guide.md and update all references"

"Move multiple files from the drafts/ folder to published/ and update all links"

"Validate my recent file moves to check for any broken links"

Verification

Restart Claude Desktop and look for the 🔧 MCP icon in the chat. If configured correctly, you'll see "markmv" listed in the connected MCP servers.

📖 Command Reference

convertCommand()

function convertCommand(patterns: string[], options: ConvertOptions): Promise<void>;

Defined in: commands/convert.ts:244

CLI command handler for convert operations.

Processes markdown files to convert link formats and path resolution according to specified options. Supports dry run mode, verbose output, and various conversion strategies.

Example

  # Convert all links to relative paths
  markmv convert docs/star.md --path-resolution relative

  # Convert to wikilink style with absolute paths
  markmv convert starstar/star.md --link-style wikilink --path-resolution absolute

  # Dry run with verbose output
  markmv convert README.md --link-style claude --dry-run --verbose

indexCommand()

function indexCommand(directory: undefined | string, cliOptions: IndexCliOptions): Promise<void>;

Defined in: commands/index.ts:131

CLI command handler for generating documentation indexes.

Creates organized documentation indexes from markdown files using various strategies. Supports multiple index types including links, imports, embeds, and hybrid modes.

Example

  # Generate a links-based index
  markmv index --type links --strategy directory

  # Generate with custom template
  markmv index docs/ --type hybrid --template custom.md

  # Dry run with verbose output
  markmv index --dry-run --verbose

🔧 Core API

createMarkMv()

function createMarkMv(): FileOperations;

Defined in: index.ts:146

Main entry point for the markmv library

Creates a new FileOperations instance for performing markdown file operations. This is the recommended way to get started with the library.

Returns

FileOperations

A new FileOperations instance

Example

  import { createMarkMv } from 'markmv';

  const markmv = createMarkMv();
  const result = await markmv.moveFile('old.md', 'new.md');
  ```;

***

### moveFile()

```ts
function moveFile(
   sourcePath: string, 
   destinationPath: string, 
options: MoveOperationOptions): Promise<OperationResult>;

Defined in: index.ts:170

Convenience function for moving a single markdown file

Parameters

sourcePath

string

The current file path

destinationPath

string

The target file path

options

MoveOperationOptions = {}

Optional configuration

Returns

Promise<OperationResult>

Promise resolving to operation result

Example

  import { moveFile } from 'markmv';

  const result = await moveFile('docs/old.md', 'docs/new.md', {
    dryRun: true
  });
  ```;

***

### moveFiles()

```ts
function moveFiles(moves: object[], options: MoveOperationOptions): Promise<OperationResult>;

Defined in: index.ts:199

Convenience function for moving multiple markdown files

Parameters

moves

object[]

Array of source/destination pairs

options

MoveOperationOptions = {}

Optional configuration

Returns

Promise<OperationResult>

Promise resolving to operation result

Example

  import { moveFiles } from 'markmv';

  const result = await moveFiles([
    { source: 'old1.md', destination: 'new1.md' },
    { source: 'old2.md', destination: 'new2.md' }
  ]);
  ```;

***

### validateOperation()

```ts
function validateOperation(result: OperationResult): Promise<{
  valid: boolean;
  brokenLinks: number;
  errors: string[];
}>;

Defined in: index.ts:228

Convenience function for validating markdown file operations

Parameters

result

OperationResult

The operation result to validate

Returns

Promise<{ valid: boolean; brokenLinks: number; errors: string[]; }>

Promise resolving to validation result

Example

  import { moveFile, validateOperation } from 'markmv';

  const result = await moveFile('old.md', 'new.md');
  const validation = await validateOperation(result);

  if (!validation.valid) {
  console.error(`Found ${validation.brokenLinks} broken links`);
  }

📖 Documentation

• 📚 Complete User Guide - Detailed usage instructions and examples
• 🔧 API Reference - TypeScript API documentation
• 🌐 REST API Docs - HTTP endpoints and examples
• 🤖 MCP Integration - AI agent setup and configuration

🛠️ Development

git clone https://github.com/ExaDev/markmv.git
cd markmv
npm install
npm run build
npm test

Contributing Guide | Development Setup

📄 License

CC BY-NC-SA 4.0 - see the LICENSE file for details.

---

📖 Documentation • 🐛 Issues • 💬 Discussions

Modules

• commands/convert
• commands
• index