{"_id":"@bnku/mdmm","_rev":"4-fb4c446006adde9ab6c2d4f72858dc32","name":"@bnku/mdmm","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@bnku/mdmm","version":"0.1.0","keywords":["mdmm","mermaid","markdown","documentation","cli","transclusion"],"license":"MIT","_id":"@bnku/mdmm@0.1.0","maintainers":[{"name":"bnku","email":"bnku@ya.ru"}],"homepage":"https://github.com/bnku/mdmm#readme","bugs":{"url":"https://github.com/bnku/mdmm/issues"},"bin":{"mdmm":"bin/mdmm.js"},"dist":{"shasum":"3d523cc59d03b4931a5d9e854813fd0af7e2828b","tarball":"https://registry.npmjs.org/@bnku/mdmm/-/mdmm-0.1.0.tgz","fileCount":17,"integrity":"sha512-Gupo7364FT8xeWFEqCc0atHU48klVJTFg+IdlQ4AskXry2B+ldhhMQUEkfZngtufNxVRwkeCrzXNnmAss4uiWw==","signatures":[{"sig":"MEUCIQDB1BoZ4zO5JMai9dQswRMn/gniwztESkMvxDn62/BnDAIgEsBlTDqh6dWFtNlgVxVuliexUFzgGTaLXubXXon6QkY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119580},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"ddf86fc614b8f0e1d4d1b69517b0bb93a77924a0","scripts":{"test":"node --test","smoke:bin":"./bin/mdmm.js --help","pack:dry-run":"npm pack --dry-run","build:examples":"./bin/mdmm.js build ./examples --output ./examples/dist","check:examples":"./bin/mdmm.js check ./examples","report:examples":"./bin/mdmm.js report ./examples --output ./examples/dist/dependencies.json","validate:examples":"node ./scripts/validate-mermaid-cli.js ./examples/dist/docs/diagram-include.md ./examples/dist/docs/fragment-include.md ./examples/dist/docs/template-diagram.md ./examples/dist/docs/template-fragment.md ./examples/dist/docs/template-nested.md"},"_npmUser":{"name":"bnku","email":"bnku@ya.ru"},"repository":{"url":"git+https://github.com/bnku/mdmm.git","type":"git"},"_npmVersion":"10.9.3","description":"MDMM CLI for reusable Mermaid includes in Markdown documentation","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jsdom":"^29.1.1","mermaid":"^11.14.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mdmm_0.1.0_1778282735287_0.7376148384270449","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@bnku/mdmm","version":"0.2.0","keywords":["mdmm","mermaid","markdown","documentation","cli","transclusion"],"license":"MIT","_id":"@bnku/mdmm@0.2.0","maintainers":[{"name":"bnku","email":"bnku@ya.ru"}],"homepage":"https://github.com/bnku/mdmm#readme","bugs":{"url":"https://github.com/bnku/mdmm/issues"},"bin":{"mdmm":"bin/mdmm.js"},"dist":{"shasum":"9ed9bf5709ca9ba967381eaf5c3de356abf5b40f","tarball":"https://registry.npmjs.org/@bnku/mdmm/-/mdmm-0.2.0.tgz","fileCount":20,"integrity":"sha512-mOL20kgDJatMkPiY70innbvYktvAIFY2s+vvQt8BEs9TkjxF60yWnyGc3QEeveF0dOM4kNspwocZQd7vNbf4Dg==","signatures":[{"sig":"MEYCIQDrpvXbuq8F357ZL/MS61tyKKAs8WfbX2t4/oJQ9HgNSgIhAOLIgxE5zXUHsM7MKCmL5jbUUpLYFH9NyC/U4tmzDNuU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":145509},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"733cbcbbeafde339183271175ee9198f6ceeed7b","scripts":{"test":"node --test","smoke:bin":"./bin/mdmm.js --help","pack:dry-run":"npm pack --dry-run","build:examples":"./bin/mdmm.js build ./examples --output ./examples/dist","check:examples":"./bin/mdmm.js check ./examples","report:examples":"./bin/mdmm.js report ./examples --output ./examples/dist/dependencies.json","validate:examples":"node ./scripts/validate-mermaid-cli.js ./examples/dist/docs/diagram-include.md ./examples/dist/docs/fragment-include.md ./examples/dist/docs/template-diagram.md ./examples/dist/docs/template-fragment.md ./examples/dist/docs/template-nested.md"},"_npmUser":{"name":"bnku","email":"bnku@ya.ru"},"repository":{"url":"git+https://github.com/bnku/mdmm.git","type":"git"},"_npmVersion":"10.9.3","description":"MDMM CLI for reusable Mermaid includes in Markdown documentation","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jsdom":"^29.1.1","mermaid":"^11.14.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mdmm_0.2.0_1778286989835_0.9469711279483446","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@bnku/mdmm","version":"0.2.1","keywords":["mdmm","mermaid","markdown","documentation","cli","transclusion"],"license":"MIT","_id":"@bnku/mdmm@0.2.1","maintainers":[{"name":"bnku","email":"bnku@ya.ru"}],"homepage":"https://github.com/bnku/mdmm#readme","bugs":{"url":"https://github.com/bnku/mdmm/issues"},"bin":{"mdmm":"bin/mdmm.js"},"dist":{"shasum":"f87e504a4f9e39e12b578027af57e3de44b56543","tarball":"https://registry.npmjs.org/@bnku/mdmm/-/mdmm-0.2.1.tgz","fileCount":20,"integrity":"sha512-+igPJ6a5BErYI/QqggOFMWNxtJ8ZrsAXixS0fkoWLj1w3899WFCV9Yvh56BbMXiyKHlk573T2ZA/w2HakP9USQ==","signatures":[{"sig":"MEUCIQCNnAFlkWD9RxaOSwk8Wfsn16Nv8DFSwchbiwazqpIgEgIgb1lcYfIK+R+NPQM7XNnHBg+1E7t+DWsQ+jg96OjWUr8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":153277},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"e550d62e90b86eea6a2762ba31f56c9a410b8fb6","scripts":{"test":"node --test","smoke:bin":"./bin/mdmm.js --help","pack:dry-run":"npm pack --dry-run","build:examples":"./bin/mdmm.js build ./examples --output ./examples/dist","check:examples":"./bin/mdmm.js check ./examples","report:examples":"./bin/mdmm.js report ./examples --output ./examples/dist/dependencies.json","validate:examples":"node ./scripts/validate-mermaid-cli.js ./examples/dist/docs"},"_npmUser":{"name":"bnku","email":"bnku@ya.ru"},"repository":{"url":"git+https://github.com/bnku/mdmm.git","type":"git"},"_npmVersion":"10.9.3","description":"MDMM CLI for reusable Mermaid includes in Markdown documentation","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jsdom":"^29.1.1","mermaid":"^11.14.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mdmm_0.2.1_1778393482817_0.5340077405306087","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@bnku/mdmm","version":"0.2.2","description":"MDMM CLI for reusable Mermaid includes in Markdown documentation","license":"MIT","type":"module","repository":{"type":"git","url":"git+https://github.com/bnku/mdmm.git"},"homepage":"https://github.com/bnku/mdmm#readme","bugs":{"url":"https://github.com/bnku/mdmm/issues"},"publishConfig":{"access":"public"},"bin":{"mdmm":"bin/mdmm.js"},"engines":{"node":">=22.0.0"},"keywords":["mdmm","mermaid","markdown","documentation","cli","transclusion"],"scripts":{"test":"node --test","build:examples":"./bin/mdmm.js build ./examples --output ./examples/dist","check:examples":"./bin/mdmm.js check ./examples","validate:examples":"node ./scripts/validate-mermaid-cli.js ./examples/dist/docs","report:examples":"./bin/mdmm.js report ./examples --output ./examples/dist/dependencies.json","smoke:bin":"./bin/mdmm.js --help","pack:dry-run":"npm pack --dry-run"},"dependencies":{"jsdom":"^29.1.1","mermaid":"^11.14.0"},"_id":"@bnku/mdmm@0.2.2","gitHead":"4b4d92dec23b12e0378c2c027259df11d0af04bb","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-7krwaNiED5o+5qY0uFfu9dsIolWUo00zVZH0I10GWW4WGzWJCyuAhPFBmErOkRhH5zN1PRzJk1Iea7aPDCUQlA==","shasum":"f8a5456f55b36b7bf1a4e9e79be50331e7c8ebc6","tarball":"https://registry.npmjs.org/@bnku/mdmm/-/mdmm-0.2.2.tgz","fileCount":20,"unpackedSize":162866,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC7Watf5pf53bstl61VFvTrav33DOeEZqfUcGG7ZWl5bwIgCvk6sKmLsNgiiXO8Y5+Ru3MTybys2lyNvY51+ZIM25A="}]},"_npmUser":{"name":"bnku","email":"bnku@ya.ru"},"directories":{},"maintainers":[{"name":"bnku","email":"bnku@ya.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mdmm_0.2.2_1778394722330_0.5663689412045867"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-08T23:25:35.165Z","modified":"2026-05-10T06:32:02.591Z","0.1.0":"2026-05-08T23:25:35.455Z","0.2.0":"2026-05-09T00:36:30.033Z","0.2.1":"2026-05-10T06:11:22.981Z","0.2.2":"2026-05-10T06:32:02.474Z"},"bugs":{"url":"https://github.com/bnku/mdmm/issues"},"license":"MIT","homepage":"https://github.com/bnku/mdmm#readme","keywords":["mdmm","mermaid","markdown","documentation","cli","transclusion"],"repository":{"type":"git","url":"git+https://github.com/bnku/mdmm.git"},"description":"MDMM CLI for reusable Mermaid includes in Markdown documentation","maintainers":[{"name":"bnku","email":"bnku@ya.ru"}],"readme":"# MDMM: Mermaid Include for Markdown Documentation\n\n---\n\n[по-русски](./README.RU.md) | [in english](./README.md)\n\n---\n\n\n`mdmm` is a CLI tool for reusing Markdown sections, Mermaid diagrams, and Mermaid fragments in Markdown documents. It lets you define shared blocks once, include them where needed, and generate plain Markdown with standard `mermaid` blocks as output.\n\nThe tool follows a simple idea: authors keep working in familiar `Markdown + Mermaid`, without a separate DSL, JSON, or YAML. `mdmm` only adds a minimal syntax for including shared Markdown blocks, diagrams, fragments, and templates, while handling reference validation, argument substitution, and final document assembly.\n\nThis makes documentation easier to maintain: repeated sections and diagrams do not need to be copied by hand, updates happen in one place, and the final output stays ready for publication and easy to read for anyone working with plain Markdown.\n\n## Table Of Contents\n\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Installation And Usage](#installation-and-usage)\n- [New Project](#new-project)\n- [Project Config](#project-config)\n- [Workflow](#workflow)\n- [The MDMM Authoring Language](#the-mdmm-authoring-language)\n  - [Declaring A Reusable Diagram](#1-declaring-a-reusable-diagram)\n  - [Including A Diagram](#2-including-a-diagram)\n  - [Declaring And Including A Markdown Block](#3-declaring-and-including-a-markdown-block)\n  - [Declaring And Including A Fragment](#4-declaring-and-including-a-fragment)\n  - [Template Arguments](#5-template-arguments)\n  - [Nested Templates And References](#6-nested-templates-and-references)\n  - [Short And Explicit References](#7-short-and-explicit-references)\n  - [Short Aliases](#8-short-aliases)\n  - [Authoring Recommendations](#9-authoring-recommendations)\n- [CLI Commands](#cli-commands)\n- [Default Values Summary](#default-values-summary)\n- [Current Limitations](#current-limitations)\n- [FAQ](#faq)\n\n## Quick Start\n\n```bash\nnpm i -g @bnku/mdmm\nmdmm init\n```\n\n```bash\nnpx @bnku/mdmm init\n```\n\nAfter `init`, you get a basic project structure, a sample shared diagram, and a starter document.\n\n## How It Works\n\n1. Store shared Markdown blocks, Mermaid diagrams, and Mermaid fragments in a library.\n2. Include them from working documents through `mdmm` directives.\n3. Run `mdmm check` to validate references, template arguments, and language rules.\n4. Use `mdmm dev` during authoring when you want watch mode with selective rebuilds.\n5. Run `mdmm build` to expand all includes and produce final Markdown.\n6. The output contains plain `mermaid` blocks ready for publication.\n\n## Installation And Usage\n\nRequirement: `Node.js 22` or newer.\n\n| Scenario | Command | When it fits |\n| --- | --- | --- |\n| Global install | `npm i -g @bnku/mdmm` | when you work with documentation on this machine regularly |\n| No installation | `npx @bnku/mdmm ...` | when you want to try the tool quickly or run a one-off build |\n\nExamples:\n\n```bash\nnpm i -g @bnku/mdmm\nmdmm --help\nmdmm check\nmdmm dev\nmdmm build\n```\n\n```bash\nnpx @bnku/mdmm --help\nnpx @bnku/mdmm init\nnpx @bnku/mdmm build\n```\n\nThe package is published on npm as `@bnku/mdmm`, but the installed CLI command remains `mdmm`.\n\nThis project also ships with an agent skill in `.agents/mdmm` that documentation authors can install into their own agent setup, either globally or inside a docs project. It helps the agent work with `mdmm` more reliably by understanding the expected project layout, the reusable block and fragment syntax, when to use `check`, `dev`, `build`, or `report`, and how to diagnose broken references, template arguments, and include-related issues while collaborating on documentation changes.\n\n## New Project\n\nThe `mdmm init` command creates a new documentation project structure.\n\n```bash\nmdmm init\n```\n\nBy default it creates:\n\n```text\n.\n|- docs/\n|  `- index.md\n|- shared/\n|  `- getting-started.md\n|- dist/\n`- mdmm.config.json\n```\n\nIf `mdmm.config.json` or starter files already exist, `init` will not overwrite them unless you pass `--force` explicitly.\n\n### Parameters For `init`\n\n| Parameter | Default | What it does |\n| --- | --- | --- |\n| `--yes` | off | accepts default values without interactive prompts |\n| `--force` | off | allows overwriting files created by `init` |\n| `--no-starter` | off | creates only directories and config, without starter Markdown files |\n\n### Default `init` Behavior\n\n| What is configured | Default value |\n| --- | --- |\n| Documents directory | `docs/` |\n| Shared library directory | `shared/` |\n| Build output directory | `dist/` |\n\nIf the command runs in a non-interactive environment, use `--yes`.\n\n## Project Config\n\n`mdmm` can work without a config file, but for regular use it is more convenient to add `mdmm.config.json` at the project root.\n\nExample:\n\n```json\n{\n  \"docsDir\": \"docs\",\n  \"sharedDir\": \"shared\",\n  \"outputDir\": \"dist\"\n}\n```\n\nAll fields are optional.\n\n### Config Fields\n\n| Field | Default value | Meaning |\n| --- | --- | --- |\n| `docsDir` | `docs` | where source Markdown documents live |\n| `sharedDir` | `shared` | where the reusable Markdown and Mermaid library lives |\n| `outputDir` | `dist` | where directory build output is written |\n\n## Workflow\n\nA typical workflow looks like this:\n\n1. Put shared Markdown blocks, diagrams, and fragments into `shared/`.\n2. Write user-facing documents in `docs/`.\n3. Include the blocks you need through `mdmm` directives.\n4. Run `mdmm check` for a fast validation of references and templates.\n5. Use `mdmm dev` while authoring when you want automatic selective rebuilds into `dist/`.\n6. Run `mdmm build` to generate final Markdown for publication.\n7. Use `mdmm report` when you need to see what is reused and where.\n\n## The MDMM Authoring Language\n\n`mdmm` adds a minimal set of constructs on top of plain Markdown. They exist only to support reusable Markdown and Mermaid content.\n\n### 1. Declaring A Reusable Diagram\n\nA reusable diagram is declared with `mermaid:block` HTML comments.\n\n````md\n<!-- mermaid:block customer-verification.overview -->\n```mermaid\nflowchart TD\nStart[Receive documents] --> Review{Documents valid?}\nReview -- Yes --> Approve[Approve customer]\nReview -- No --> Fix[Request corrections]\n```\n<!-- /mermaid:block -->\n````\n\nThat block can later be included from other documents through `mermaid-include`.\n\n### 2. Including A Diagram\n\nThe simplest way to include a shared block is:\n\n````md\n```mermaid-include\ncustomer-verification.overview\n```\n````\n\nThis form is called a short reference.\n\nIf you want to point to a specific file explicitly:\n\n````md\n```mermaid-include\n../shared/customer-verification.md#customer-verification.overview\n```\n````\n\nAfter the build, the `mermaid-include` block is replaced with a standard `mermaid` block.\n\n### 3. Declaring And Including A Markdown Block\n\nUse a Markdown block when you want to reuse prose, headings, lists, or mixed Markdown content.\n\n````md\n<!-- markdown:block customer-verification.section -->\n## Customer verification\n\nThis section stays in plain Markdown.\n\n```mermaid-include\ncustomer-verification.overview\n```\n<!-- /markdown:block -->\n````\n\nIncluding it from another document:\n\n````md\n```markdown-include\ncustomer-verification.section\n```\n````\n\nAfter the build, the `markdown-include` block is replaced with the rendered Markdown content.\n\n### 4. Declaring And Including A Fragment\n\nA fragment is useful when you need to insert a standard subprocess into a larger diagram.\n\nA fragment is declared with a dedicated `mermaid:fragment` construct.\n\n````md\n<!-- mermaid:fragment verification exports=entry,success,fail -->\n```mermaid\nflowchart TD\nentry[Start verification]\nentry --> check{Documents valid?}\ncheck -- Yes --> success[Verification passed]\ncheck -- No --> fail[Corrections required]\n```\n<!-- /mermaid:fragment -->\n````\n\nIncluding a fragment inside a diagram:\n\n````md\n```mermaid\nflowchart LR\nStart --> kyc__entry\n%% include: verification as kyc\nkyc__success --> Done\n```\n````\n\nIncluding it by explicit path:\n\n````md\n```mermaid\nflowchart LR\nStart --> kyc__entry\n%% include: ../shared/verification-fragment.md#verification as kyc\nkyc__success --> Done\n```\n````\n\nImportant fragment rules:\n\n- fragments are declared through `mermaid:fragment ...`;\n- every fragment include must define an `alias` through `as ...`;\n- fragment names can be short and do not need a `.fragment` suffix;\n- `mdmm` automatically rewrites internal node ids into `<alias>__<node-id>`;\n- from outside, you can reference only the nodes listed in `exports`;\n- the first line with the diagram type is kept for the author but is not inserted into the outer diagram.\n\n### 5. Template Arguments\n\nMarkdown blocks, diagrams, and fragments can use simple parameters.\n\nExample template:\n\n````md\n<!-- mermaid:block approval.overview -->\n```mermaid\nflowchart TD\nstart([Start]) --> owner[\"%owner%\"]\nowner --> review{\"Approval: %reviewer|Finance%\"}\nreview -->|Escalate| escalator[\"%escalator|Function head%\"]\n```\n<!-- /mermaid:block -->\n````\n\nExample templated fragment:\n\n````md\n<!-- mermaid:fragment approval exports=entry,done -->\n```mermaid\nflowchart TD\nentry[\"%owner%\"]\nentry --> done[\"Approved by: %reviewer|Finance%\"]\n```\n<!-- /mermaid:fragment -->\n````\n\n### Placeholder Forms\n\n| Form | Meaning | Default behavior |\n| --- | --- | --- |\n| `%name%` | required argument | if the argument is not passed, the command fails |\n| `%name\\|Text%` | argument with a default value | if the argument is not passed, the text after `\\|` is used |\n\nCompact one-line form for a diagram:\n\n````md\n```mermaid-include\napproval.overview owner=\"Risk office\" reviewer=Legal\n```\n````\n\nMulti-line form for a diagram:\n\n````md\n```mermaid-include\napproval.overview\nowner = Operations\nescalator = Department head\n```\n````\n\nCompact form for a fragment:\n\n````md\n```mermaid\nflowchart LR\nStart --> lane__entry\n%% include: approval as lane owner=\"Risk office\" reviewer=Legal\nlane__done --> End\n```\n````\n\nMulti-line form for a fragment:\n\n````md\n```mermaid\nflowchart LR\nStart --> lane__entry\n%% include: approval as lane\n%% owner = Operations\n%% reviewer = Finance\nlane__done --> End\n```\n````\n\nTemplate rules:\n\n- an unknown argument causes an error;\n- a missing required argument causes an error;\n- redeclaring the same argument causes an error;\n- in one-line form, values with spaces must be quoted.\n\n### 6. Nested Templates And References\n\nA template can include another template or fragment.\n\nExample:\n\n````md\n<!-- mermaid:block review.wrapper -->\n```mermaid\nflowchart LR\nStart --> lane__entry\n%% include: %fragmentRef|review% as lane\n%% reviewer = %reviewer|Finance%\nlane__done --> End\n```\n<!-- /mermaid:block -->\n````\n\nCall site:\n\n````md\n```mermaid-include\nreview.wrapper fragmentRef=audit reviewer=Legal\n```\n````\n\nCall site with an explicit path:\n\n````md\n```mermaid-include\nreview.wrapper fragmentRef=../shared/library.md#audit reviewer=Legal\n```\n````\n\nPath resolution rules in nested templates:\n\n- if a relative path is passed explicitly as a template argument, it is resolved relative to the document that calls the template;\n- if a relative path is defined as a default value inside the template itself, it is resolved relative to the template file.\n\n### 7. Short And Explicit References\n\n| Reference form | Example | Where it is resolved |\n| --- | --- | --- |\n| Short | `customer-verification.overview` | across all `.md` files inside `sharedDir`, recursively, within the requested block type |\n| Explicit | `../shared/customer-verification.md#customer-verification.overview` | the path is resolved relative to the current document |\n\nShort references are more convenient for daily work. `mdmm` resolves them by `block id` across the entire `sharedDir` tree, but it scopes the lookup by the include kind: `mermaid-include` looks for reusable diagrams, `markdown-include` looks for reusable Markdown blocks, and fragment includes look for reusable fragments. That means the same `block id` can exist once per block type without creating a short-ref conflict. Explicit references are useful when you need to point to a specific file unambiguously.\n\n### 8. Short Aliases\n\nShort aliases are supported for authors who prefer less typing:\n\n- `mm:block` for `mermaid:block`\n- `mm:fragment` for `mermaid:fragment`\n- `md:block` for `markdown:block`\n- `mm-include` for `mermaid-include`\n- `md-include` for `markdown-include`\n\nThe examples in this README intentionally use the long forms because they are clearer for first-time readers. The short aliases behave the same way.\n\n### 9. Authoring Recommendations\n\n- use template arguments in labels, comments, and argument values;\n- do not use `%...%` in node ids, `alias`, or the diagram type line;\n- give blocks stable and readable `block id` values;\n- for fragments, think through the public entry and exit points exposed through `exports`.\n\n## CLI Commands\n\n### General Commands And Global Options\n\nIf you run `mdmm` without a command, it prints help and a short quick-start message.\n\n```bash\nmdmm\nmdmm --help\nmdmm --version\n```\n\nEvery command also has its own help:\n\n```bash\nmdmm build --help\nmdmm check --help\nmdmm dev --help\n```\n\n### Global Options\n\n| Option | Default | What it does |\n| --- | --- | --- |\n| `--help`, `-h` | off | shows general help |\n| `--version`, `-v` | off | shows the installed `mdmm` version |\n| `--no-color` | off | disables colored output |\n| `NO_COLOR` | unset | if this environment variable is set, colored output is disabled |\n\nColored output is enabled automatically only in terminals with TTY support.\n\n## Command `init`\n\nSyntax:\n\n```bash\nmdmm init [--yes] [--force] [--no-starter]\n```\n\nWhat the command does:\n\n- creates `mdmm.config.json`;\n- creates `docs/`, `shared/`, and `dist/` directories;\n- in the default mode, adds starter Markdown files.\n\n### Parameters For `init`\n\n| Parameter | Default | What it does |\n| --- | --- | --- |\n| `--yes` | off | accepts the default project structure without prompts |\n| `--force` | off | allows overwriting files created by `init` |\n| `--no-starter` | off | does not create `docs/index.md` or `shared/getting-started.md` |\n\n## Command `check`\n\nSyntax:\n\n```bash\nmdmm check [<input.md|input-dir>] [--max-include-depth <n>]\n```\n\nWhen to use it:\n\n- when you want a fast validation of references;\n- when you edited templates or fragments;\n- when you do not need output files yet and only want validation.\n\nWhat `check` validates:\n\n- that blocks and files exist;\n- that short and explicit references are valid;\n- that `alias` and `exports` are valid;\n- that required and unknown template arguments are handled correctly;\n- include nesting depth.\n\nWhat `check` does not do:\n\n- it does not write files;\n- it does not run final Mermaid validation on the rendered output.\n\n### Parameters For `check`\n\n| Parameter | Default | What it does |\n| --- | --- | --- |\n| `<input.md|input-dir>` | `docsDir` from config or `./docs` | sets the file or directory to validate |\n| `--max-include-depth <n>` | `5` | limits nested include depth |\n\nExamples:\n\n```bash\nmdmm check\nmdmm check ./docs\nmdmm check ./docs/customer-flow.md\nmdmm check ./docs --max-include-depth 8\n```\n\n## Command `dev`\n\nSyntax:\n\n```bash\nmdmm dev [<input-dir>] [--output <output-path>] [--max-include-depth <n>] [--no-validate]\n```\n\nWhen to use it:\n\n- when you are actively editing docs or shared Mermaid blocks;\n- when you want `dist/` to stay up to date without rerunning `build` by hand;\n- when full project rebuilds would be unnecessarily expensive after a small change.\n\nWhat `dev` does:\n\n- performs an initial directory build;\n- watches source docs, the shared library, and project config;\n- rebuilds only the affected Markdown documents when dependencies change;\n- keeps the last successful output if an updated batch fails;\n- keeps watching after errors so the next fix can rebuild automatically.\n\n### Parameters For `dev`\n\n| Parameter | Default | What it does |\n| --- | --- | --- |\n| `<input-dir>` | `docsDir` from config or `./docs` | sets the directory to watch and rebuild |\n| `--output <output-path>` | `outputDir` from config or `./dist` | sets where rebuilt Markdown files are written |\n| `--max-include-depth <n>` | `5` | limits nested include depth |\n| `--no-validate` | off | disables final Mermaid validation during watch rebuilds |\n\n### Important `dev` Properties\n\n- `dev` currently watches a directory input only;\n- it uses dependency tracking to avoid rebuilding unrelated docs;\n- adding or removing shared blocks can still trigger rebuilds for short-reference users;\n- if a rebuild fails, the previous successful file contents stay on disk.\n\nExamples:\n\n```bash\nmdmm dev\nmdmm dev ./docs --output ./dist/docs\nmdmm dev ./docs --no-validate\n```\n\n## Command `build`\n\nSyntax:\n\n```bash\nmdmm build [<input.md|input-dir>] [--output <output-path>] [--max-include-depth <n>] [--no-validate]\n```\n\nWhen to use it:\n\n- when you need final Markdown for publication;\n- when you want all includes expanded into standard Mermaid blocks;\n- when you want an additional validation pass on the final Mermaid content.\n\nWhat `build` does:\n\n- expands Markdown includes, diagram includes, and fragment includes;\n- substitutes template arguments;\n- validates final Mermaid blocks by default;\n- writes the result to a file or directory;\n- preserves relative file structure when building a directory.\n\n### Parameters For `build`\n\n| Parameter | Default | What it does |\n| --- | --- | --- |\n| `<input.md|input-dir>` | `docsDir` from config or `./docs` | sets the file or directory to build |\n| `--output <output-path>` | depends on the mode | sets where the result is written |\n| `--max-include-depth <n>` | `5` | limits nested include depth |\n| `--no-validate` | off | disables final Mermaid validation |\n\n### Default `build` Behavior\n\n| Scenario | Behavior |\n| --- | --- |\n| Building a single file without `--output` | prints the result to stdout |\n| Building a single file with `--output` | writes the result to the specified file |\n| Building a directory without `--output` | writes the result to `outputDir` from config or `./dist` |\n| Building a directory with `--output` | writes the result to the specified directory |\n| Mermaid validation | enabled |\n\n### Important `build` Properties\n\n- if the final Mermaid output is invalid, the command fails;\n- when building a directory, `mdmm` does not write partial output: it validates everything first and writes files only after the full run succeeds;\n- if the input is a directory, `mdmm` processes all `.md` files recursively;\n- if the recursive input is the project root, the shared library and build output directories are skipped automatically.\n\nExamples:\n\n```bash\nmdmm build\nmdmm build ./docs --output ./dist/docs\nmdmm build ./docs/customer-flow.md\nmdmm build ./docs/customer-flow.md --output ./dist/customer-flow.md\nmdmm build ./docs --no-validate\n```\n\n## Command `report`\n\nSyntax:\n\n```bash\nmdmm report [<input.md|input-dir>] [--output <report-path>] [--format <json|markdown>]\n```\n\nWhen to use it:\n\n- when you want to understand where shared blocks are used;\n- when you are cleaning up the shared block library;\n- when you need to estimate the impact of changing a shared block.\n\nWhat the report contains:\n\n- the list of processed Markdown files;\n- dependencies for each file;\n- dependency type: `markdown`, `diagram`, or `fragment`;\n- the original author reference;\n- the target file and `block id`;\n- the `alias` for fragment includes;\n- passed template arguments;\n- a block usage summary.\n\nFormats:\n\n- `json` is the default and is meant for tooling or scripting;\n- `markdown` is a human-readable view with a summary, hotspots, block usage index, and file dependency index.\n\n### Parameters For `report`\n\n| Parameter | Default | What it does |\n| --- | --- | --- |\n| `<input.md|input-dir>` | `docsDir` from config or `./docs` | sets the file or directory for the report |\n| `--output <report-path>` | stdout | writes the report to a file |\n| `--format <json|markdown>` | `json` | selects machine-readable JSON or a human-readable Markdown report |\n\nExamples:\n\n```bash\nmdmm report\nmdmm report ./docs --output ./dist/dependencies.json\nmdmm report ./docs --format markdown --output ./dist/dependencies.md\nmdmm report ./docs/customer-flow.md\n```\n\n## Command `adopt`\n\nSyntax:\n\n```bash\nmdmm adopt\n```\n\nThe command is already reserved in the CLI, but it does not yet perform an automatic migration for an existing project. Right now it prints guidance and does not change any files.\n\nIt is intended for a future workflow where an existing documentation set needs repeated diagrams identified and the project prepared carefully for `mdmm` adoption.\n\n## Default Values Summary\n\n| Area | Parameter | Default value |\n| --- | --- | --- |\n| Project config | `docsDir` | `docs` |\n| Project config | `sharedDir` | `shared` |\n| Project config | `outputDir` | `dist` |\n| `init` | mode | interactive |\n| `init` | starter files | created |\n| `check` | input path | `docsDir` from config or `./docs` |\n| `check` | `--max-include-depth` | `5` |\n| `dev` | input path | `docsDir` from config or `./docs` |\n| `dev` | output without `--output` | `outputDir` from config or `./dist` |\n| `dev` | `--max-include-depth` | `5` |\n| `dev` | Mermaid validation | enabled |\n| `build` | input path | `docsDir` from config or `./docs` |\n| `build` | `--max-include-depth` | `5` |\n| `build` | Mermaid validation | enabled |\n| `build` | single-file output without `--output` | stdout |\n| `build` | directory output without `--output` | `outputDir` from config or `./dist` |\n| `report` | input path | `docsDir` from config or `./docs` |\n| `report` | output without `--output` | stdout |\n| Colored output | `--no-color` | off |\n| Colored output | `NO_COLOR` | unset |\n\n## Current Limitations\n\n- a reusable diagram block must ultimately expand into exactly one `mermaid` block;\n- a short reference is resolved by `block id` within its block type across all Markdown files inside `sharedDir`, recursively;\n- an explicit reference must always use the `path/to/file.md#block-id` form;\n- fragments allow external references only to nodes listed in `exports`;\n- `alias` must be unique within a single `mermaid` block;\n- template arguments are not meant for node ids, `alias`, or the diagram type line;\n- nesting depth is limited by `--max-include-depth`;\n- `check` can succeed while `build` fails if the final Mermaid output is invalid;\n- `dev` currently supports only directory input, not single-file watch mode;\n- `adopt` does not yet perform a real migration.\n\n## FAQ\n\n**Do I need `mdmm.config.json`?**\n\nNo. The tool can work without a config file. But for regular project work, the config is more convenient because it defines the document, shared-library, and output directories once.\n\n**Can I run `mdmm` on a single file?**\n\n`check`, `build`, and `report` accept either a single `.md` file or a directory. `dev` currently watches a directory only.\n\n**Where does `mdmm` look for short references?**\n\nOnly inside `sharedDir`. The lookup is scoped by block type: `mermaid-include` resolves diagram blocks, `markdown-include` resolves Markdown blocks, and fragment includes resolve fragment blocks. If you need to point to a specific file, use an explicit reference like `path/to/file.md#block-id`.\n\n**Why does `build` sometimes fail even when `check` passes?**\n\n`check` validates `mdmm` language rules, but it does not run final Mermaid validation. By default, `build` validates the fully rendered Mermaid output.\n\n**What do I get after `build`?**\n\nPlain Markdown where all `mdmm` directives have already been expanded, with reusable Markdown content inlined and Mermaid output left as standard `mermaid` blocks.\n","readmeFilename":"README.md"}