TypeScript CLI for markdown file operations with intelligent link refactoring
npm install markmv``bash`
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.
- 🚀 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
`bashUse directly with npx (recommended)
npx markmv --help
Requirements: Node.js >= 18.0.0
🚀 Quick Start
bash
Move a file and update all references
npx markmv move old-doc.md new-location/renamed-doc.mdSplit a large file by headers
npx markmv split large-guide.md --strategy headers --header-level 2Join multiple files
npx markmv join intro.md setup.md usage.md --output complete-guide.mdGenerate documentation index
npx markmv index --type links --strategy directory
`🌐 Access Methods
markmv provides multiple interfaces for different use cases:
$3
bash
npx markmv move old.md new.md --json # JSON output for scripting
`$3
bash
npx --package=markmv markmv-api # Start HTTP server on port 3000
`$3
bash
npx --package=markmv markmv-mcp # Model Context Protocol server
`$3
typescript
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:
$3
Add markmv to your Claude Desktop configuration:
macOS:
Windows: %APPDATA%/Claude/claude_desktop_config.jsonjson
{
"mcpServers": {
"markmv": {
"command": "npx",
"args": [
"--package=markmv",
"markmv-mcp"
],
"env": {
"NODE_OPTIONS": "--no-warnings"
}
}
}
}
`$3
Once configured, Claude can use these markmv tools:
-
- Move/rename files with link updates
- move_files - Move multiple files in batch
- validate_operation - Check for broken linksNote: Additional tools (split, join, merge, convert, index) will be added in future releases.
$3
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"
$3
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
$3
`typescript
function convertCommand(patterns: string[], options: ConvertOptions): Promise;
`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
bash
# 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
`$3
typescript
function indexCommand(directory: undefined | string, cliOptions: IndexCliOptions): Promise;
`Defined in: commands/index.ts:140
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
bash
# 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
$3
ts
function createMarkMv(): FileOperations;
`Defined in: index.ts:155
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
A new FileOperations instance
#### Example
typescript
import { createMarkMv } from 'markmv'; const markmv = createMarkMv();
const result = await markmv.moveFile('old.md', 'new.md');
`;*
$3
`ts
function moveFile(
sourcePath: string,
destinationPath: string,
options: MoveOperationOptions): Promise;
`Defined in: index.ts:179
Convenience function for moving a single markdown file
#### Parameters
##### sourcePath
The current file path
##### destinationPath
The target file path
##### options
= {}Optional configuration
#### Returns
\<OperationResult\>Promise resolving to operation result
#### Example
`typescript
import { moveFile } from 'markmv'; const result = await moveFile('docs/old.md', 'docs/new.md', {
dryRun: true
});
`;*
$3
`ts
function moveFiles(moves: object[], options: MoveOperationOptions): Promise;
`Defined in: index.ts:208
Convenience function for moving multiple markdown files
#### Parameters
##### moves
[]Array of source/destination pairs
##### options
MoveOperationOptions = {}Optional configuration
#### Returns
\<OperationResult\>Promise resolving to operation result
#### Example
`typescript
import { moveFiles } from 'markmv'; const result = await moveFiles([
{ source: 'old1.md', destination: 'new1.md' },
{ source: 'old2.md', destination: 'new2.md' }
]);
`;*
$3
`ts
function validateOperation(result: OperationResult): Promise<{
valid: boolean;
brokenLinks: number;
errors: string[];
}>;
`Defined in: index.ts:237
Convenience function for validating markdown file operations
#### Parameters
##### result
The operation result to validate
#### Returns
\<\{
valid: boolean;
brokenLinks: number;
errors: string[];
\}\>Promise resolving to validation result
#### Example
`typescript
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
bash
git clone https://github.com/ExaDev/markmv.git
cd markmv
npm install
npm run build
npm test
``Contributing Guide | Development Setup
CC BY-NC-SA 4.0 - see the LICENSE file for details.
---