{"id":28818481,"url":"https://github.com/exadev/markmv","last_synced_at":"2026-03-09T18:12:26.302Z","repository":{"id":298313069,"uuid":"999331573","full_name":"ExaDev/markmv","owner":"ExaDev","description":"Intelligent TypeScript CLI for markdown file operations with automatic link refactoring. Move, split, join, and merge markdown files while preserving all links and references.","archived":false,"fork":false,"pushed_at":"2025-06-16T12:42:02.000Z","size":2297,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-18T19:05:36.352Z","etag":null,"topics":["automatic-links","cli","command-line","content-management","developer-tools","documentation","documentation-tools","file-management","file-operations","join-files","link-refactoring","markdown","markdown-processor","merge-files","move-files","nodejs","obsidian-compatibility","split-files","typescript"],"latest_commit_sha":null,"homepage":"https://exadev.github.io/markmv/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ExaDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-10T05:15:13.000Z","updated_at":"2025-06-16T12:42:04.000Z","dependencies_parsed_at":"2025-06-10T13:42:04.070Z","dependency_job_id":null,"html_url":"https://github.com/ExaDev/markmv","commit_stats":null,"previous_names":["exadev/markmv"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/ExaDev/markmv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExaDev%2Fmarkmv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExaDev%2Fmarkmv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExaDev%2Fmarkmv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExaDev%2Fmarkmv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ExaDev","download_url":"https://codeload.github.com/ExaDev/markmv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExaDev%2Fmarkmv/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260616555,"owners_count":23036867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automatic-links","cli","command-line","content-management","developer-tools","documentation","documentation-tools","file-management","file-operations","join-files","link-refactoring","markdown","markdown-processor","merge-files","move-files","nodejs","obsidian-compatibility","split-files","typescript"],"created_at":"2025-06-18T19:05:34.458Z","updated_at":"2026-03-09T18:12:26.294Z","avatar_url":"https://github.com/ExaDev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# markmv ✏️\n\n```bash\nnpx markmv --help\n```\n\n[![CI](https://github.com/ExaDev/markmv/actions/workflows/main.yml/badge.svg)](https://github.com/ExaDev/markmv/actions/workflows/main.yml)\n[![npm version](https://badge.fury.io/js/markmv.svg)](https://badge.fury.io/js/markmv)\n[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)\n\n\u003e TypeScript CLI for markdown file operations with intelligent link refactoring\n\n**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.\n\n## ✨ Key Features\n\n- 🚀 **Move files/directories** with automatic link updates\n- ✂️ **Split large files** by headers, size, or manual markers  \n- 🔗 **Join multiple files** with conflict resolution\n- 🧠 **Merge content** with interactive conflict handling\n- 📚 **Generate indexes** for documentation organization\n- 🌐 **Multiple access methods**: CLI, REST API, MCP, and programmatic\n\n## 📦 Installation\n\n```bash\n# Use directly with npx (recommended)\nnpx markmv --help\n\n# Install globally\nnpm install -g markmv\n\n# Install as library\nnpm install markmv\n```\n\n**Requirements:** Node.js \u003e= 18.0.0\n\n## 🚀 Quick Start\n\n```bash\n# Move a file and update all references\nnpx markmv move old-doc.md new-location/renamed-doc.md\n\n# Split a large file by headers\nnpx markmv split large-guide.md --strategy headers --header-level 2\n\n# Join multiple files\nnpx markmv join intro.md setup.md usage.md --output complete-guide.md\n\n# Generate documentation index\nnpx markmv index --type links --strategy directory\n```\n\n## 🌐 Access Methods\n\nmarkmv provides multiple interfaces for different use cases:\n\n### CLI Tool\n```bash\nnpx markmv move old.md new.md --json  # JSON output for scripting\n```\n\n### REST API Server\n```bash\nnpx --package=markmv markmv-api  # Start HTTP server on port 3000\n```\n\n### MCP Server (AI Integration)\n```bash\nnpx --package=markmv markmv-mcp  # Model Context Protocol server\n```\n\n### Programmatic API\n```typescript\nimport { moveFile } from 'markmv';\nconst result = await moveFile('old.md', 'new.md');\n```\n\n## 🤖 MCP Setup (AI Integration)\n\nThe markmv MCP server enables AI agents (like Claude) to use markmv functionality directly. Here's how to set it up:\n\n### Claude Desktop Configuration\n\nAdd markmv to your Claude Desktop configuration:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"markmv\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"--package=markmv\",\n        \"markmv-mcp\"\n      ],\n      \"env\": {\n        \"NODE_OPTIONS\": \"--no-warnings\"\n      }\n    }\n  }\n}\n```\n\n### Available MCP Tools\n\nOnce configured, Claude can use these markmv tools:\n\n- **`move_file`** - Move/rename files with link updates\n- **`move_files`** - Move multiple files in batch  \n- **`validate_operation`** - Check for broken links\n\n*Note: Additional tools (split, join, merge, convert, index) will be added in future releases.*\n\n### Example Usage with Claude\n\nAfter setup, you can ask Claude to:\n\n\u003e \"Use markmv to move `docs/old-guide.md` to `guides/new-guide.md` and update all references\"\n\n\u003e \"Move multiple files from the `drafts/` folder to `published/` and update all links\"\n\n\u003e \"Validate my recent file moves to check for any broken links\"\n\n### Verification\n\nRestart Claude Desktop and look for the 🔧 MCP icon in the chat. If configured correctly, you'll see \"markmv\" listed in the connected MCP servers.\n\n## 📖 Command Reference\n\n### convertCommand()\n\n```typescript\nfunction convertCommand(patterns: string[], options: ConvertOptions): Promise\u003cvoid\u003e;\n```\n\nDefined in: [commands/convert.ts:244](https://github.com/ExaDev/markmv/blob/main/src/commands/convert.ts#L244)\n\nCLI command handler for convert operations.\n\nProcesses markdown files to convert link formats and path resolution according to specified\noptions. Supports dry run mode, verbose output, and various conversion strategies.\n\n#### Example\n\n```bash\n  # Convert all links to relative paths\n  markmv convert docs/star.md --path-resolution relative\n\n  # Convert to wikilink style with absolute paths\n  markmv convert starstar/star.md --link-style wikilink --path-resolution absolute\n\n  # Dry run with verbose output\n  markmv convert README.md --link-style claude --dry-run --verbose\n```\n\n### indexCommand()\n\n```typescript\nfunction indexCommand(directory: undefined | string, cliOptions: IndexCliOptions): Promise\u003cvoid\u003e;\n```\n\nDefined in: [commands/index.ts:140](https://github.com/ExaDev/markmv/blob/main/src/commands/index.ts#L140)\n\nCLI command handler for generating documentation indexes.\n\nCreates organized documentation indexes from markdown files using various strategies. Supports\nmultiple index types including links, imports, embeds, and hybrid modes.\n\n#### Example\n\n```bash\n  # Generate a links-based index\n  markmv index --type links --strategy directory\n\n  # Generate with custom template\n  markmv index docs/ --type hybrid --template custom.md\n\n  # Dry run with verbose output\n  markmv index --dry-run --verbose\n```\n\n## 🔧 Core API\n\n### createMarkMv()\n\n```ts\nfunction createMarkMv(): FileOperations;\n```\n\nDefined in: [index.ts:155](https://github.com/ExaDev/markmv/blob/main/src/index.ts#L155)\n\nMain entry point for the markmv library\n\nCreates a new FileOperations instance for performing markdown file operations. This is the\nrecommended way to get started with the library.\n\n#### Returns\n\n[`FileOperations`](#fileoperations)\n\nA new FileOperations instance\n\n#### Example\n\n```typescript\n  import { createMarkMv } from 'markmv';\n\n  const markmv = createMarkMv();\n  const result = await markmv.moveFile('old.md', 'new.md');\n  ```;\n\n***\n\n### moveFile()\n\n```ts\nfunction moveFile(\n   sourcePath: string, \n   destinationPath: string, \noptions: MoveOperationOptions): Promise\u003cOperationResult\u003e;\n```\n\nDefined in: [index.ts:179](https://github.com/ExaDev/markmv/blob/main/src/index.ts#L179)\n\nConvenience function for moving a single markdown file\n\n#### Parameters\n\n##### sourcePath\n\n`string`\n\nThe current file path\n\n##### destinationPath\n\n`string`\n\nThe target file path\n\n##### options\n\n[`MoveOperationOptions`](#moveoperationoptions) = `{}`\n\nOptional configuration\n\n#### Returns\n\n`Promise`\\\u003c[`OperationResult`](#operationresult)\\\u003e\n\nPromise resolving to operation result\n\n#### Example\n\n```typescript\n  import { moveFile } from 'markmv';\n\n  const result = await moveFile('docs/old.md', 'docs/new.md', {\n    dryRun: true\n  });\n  ```;\n\n***\n\n### moveFiles()\n\n```ts\nfunction moveFiles(moves: object[], options: MoveOperationOptions): Promise\u003cOperationResult\u003e;\n```\n\nDefined in: [index.ts:208](https://github.com/ExaDev/markmv/blob/main/src/index.ts#L208)\n\nConvenience function for moving multiple markdown files\n\n#### Parameters\n\n##### moves\n\n`object`[]\n\nArray of source/destination pairs\n\n##### options\n\n[`MoveOperationOptions`](#moveoperationoptions) = `{}`\n\nOptional configuration\n\n#### Returns\n\n`Promise`\\\u003c[`OperationResult`](#operationresult)\\\u003e\n\nPromise resolving to operation result\n\n#### Example\n\n```typescript\n  import { moveFiles } from 'markmv';\n\n  const result = await moveFiles([\n    { source: 'old1.md', destination: 'new1.md' },\n    { source: 'old2.md', destination: 'new2.md' }\n  ]);\n  ```;\n\n***\n\n### validateOperation()\n\n```ts\nfunction validateOperation(result: OperationResult): Promise\u003c{\n  valid: boolean;\n  brokenLinks: number;\n  errors: string[];\n}\u003e;\n```\n\nDefined in: [index.ts:237](https://github.com/ExaDev/markmv/blob/main/src/index.ts#L237)\n\nConvenience function for validating markdown file operations\n\n#### Parameters\n\n##### result\n\n[`OperationResult`](#operationresult)\n\nThe operation result to validate\n\n#### Returns\n\n`Promise`\\\u003c\\{\n  `valid`: `boolean`;\n  `brokenLinks`: `number`;\n  `errors`: `string`[];\n\\}\\\u003e\n\nPromise resolving to validation result\n\n#### Example\n\n```typescript\n  import { moveFile, validateOperation } from 'markmv';\n\n  const result = await moveFile('old.md', 'new.md');\n  const validation = await validateOperation(result);\n\n  if (!validation.valid) {\n  console.error(`Found ${validation.brokenLinks} broken links`);\n  }\n  ```\n\n## 📖 Documentation\n\n- 📚 **[Complete User Guide](https://exadev.github.io/markmv/)** - Detailed usage instructions and examples\n- 🔧 **[API Reference](https://exadev.github.io/markmv/)** - TypeScript API documentation  \n- 🌐 **[REST API Docs](https://exadev.github.io/markmv/)** - HTTP endpoints and examples\n- 🤖 **[MCP Integration](https://exadev.github.io/markmv/)** - AI agent setup and configuration\n\n## 🛠️ Development\n\n```bash\ngit clone https://github.com/ExaDev/markmv.git\ncd markmv\nnpm install\nnpm run build\nnpm test\n```\n\n**[Contributing Guide](https://github.com/ExaDev/markmv/blob/main/CONTRIBUTING.md)** | **[Development Setup](https://exadev.github.io/markmv/)**\n\n## 📄 License\n\n[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[📖 Documentation](https://exadev.github.io/markmv/)** • **[🐛 Issues](https://github.com/ExaDev/markmv/issues)** • **[💬 Discussions](https://github.com/ExaDev/markmv/discussions)**\n\n\u003c/div\u003e\n\n## Modules\n\n- [commands/convert](commands.convert.md)\n- [commands](commands.md)\n- [index](index.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexadev%2Fmarkmv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexadev%2Fmarkmv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexadev%2Fmarkmv/lists"}