Markdown Utils
Markdown Utils creates and manages Markdown documents across configured repositories. VS Code commands and the mdutils CLI share document numbering, link validation, and lifecycle logic.
Features
- Create documents from configurable types and Markdown templates: plans, issues, ADRs, RFCs, brainstorming, research, guides, runbooks, quickstarts, checklists, gists, meeting notes, notes and more. Add, rename or remove types in
.markdownutils.jsonc without code changes.
- Numbered types (for example
DEV-0001, ISS-0001, ADR-0001) get stable IDs in the filename and frontmatter; unnumbered types are named by slug.
- Create Active or Draft DEV plans in one or several repositories with reciprocal project-aware relationships.
- Open related plans by
(project, id), including plans in draft, active, or done folders or other configured repositories.
- Validate Markdown links, preview repairs, complete/reopen DEV plans, and promote drafts.
- Run essential creation, link, and lifecycle operations from the CLI. Mutations require
--yes.
Quick start
Install the extension in VS Code and open a repository. Run Markdown Utils: Initialize Repository Configuration, use the final option in New Markdown File, or select the initialization action at the bottom of the extension's Explorer actions. Enter a project key to create a commented .markdownutils.jsonc at the workspace root, even when a nested folder is selected. Existing configuration is offered for opening, never overwritten.
The generated file declares the repository's document types and where the Markdown templates live. A trimmed example:
{
"version": 1,
// Stable project key used by related-plan references.
"project": "backend",
// Root of the documentation tree; numbered IDs are scanned recursively under it.
"docsRoot": "docs",
"devDir": "docs/dev",
// false: DEV plans stay directly in devDir.
// true: plans live in devDir/draft, devDir/active, devDir/done.
"requiresDevLifecycleFolders": false,
"relatedProjects": {
"frontend": { "path": "../frontend", "docsRoot": "docs", "devDir": "docs/dev", "vscodeProfile": "Frontend" },
"mobile": { "path": "../mobile", "docsRoot": "docs", "devDir": "docs/dev" }
},
"numbering": { "padding": 4 },
// Document types: each key is the frontmatter `type` value.
"types": {
"implementation-plan": { "label": "Implementation plan", "order": 10, "prefix": "DEV", "dir": "docs/dev", "statuses": ["draft", "active", "completed"], "lifecycle": "dev" },
"issue": { "label": "Issue", "order": 20, "prefix": "ISS", "aliases": ["IID"], "dir": "docs/issues", "template": "docs/templates/template-issue.md", "statuses": ["draft", "open", "in-progress", "closed"] },
"tech-note": { "label": "Tech note", "order": 70, "dir": "docs/tech-notes", "template": "docs/templates/template-tech-note.md", "statuses": ["draft", "active"] }
}
}
init writes the full catalogue (see Configurable document types) and the template files under docs/templates/. Repositories configured before the types registry (using adrDir, gidDir, iidDir and bidDir) keep working unchanged; run mdutils migrate to adopt the new format.
Paths are relative to the repository containing the configuration. Related repositories need not be open in the current VS Code workspace. Each configured devDir must stay inside its repository after symbolic links are resolved.
Right-click a folder in the Explorer:
- Choose Markdown Utils: New Development Document to make one DEV plan, or Markdown Utils: New Development Documents (paired) to choose several repositories.
- Choose Active (default) or Draft, then enter the number and title. Active plans use the next DEV number; drafts always use the placeholder
DEV-0000, are created in devDir/draft/ without asking for a number, and require requiresDevLifecycleFolders: true. Choosing an existing number for any numbered document shows a warning and requires an extra confirmation. Paired plans share an ID/title and receive reciprocal relationships.
- Use Markdown Utils: Open Related Plan to choose a referenced plan, or Markdown Utils: Validate Links to display the full read-only report.
- Use Complete Plan, Reopen Plan, or Set as Active on eligible Explorer files. Set as Active is also available in the Command Palette (Cmd+Shift+P on macOS) for the current draft. Review the preview before confirming.
- Use Markdown Utils: Create Agent Skill to scaffold
.agents/skills/markdownutils/ with SKILL.md, references/, scripts/, and assets/.
Set as Active moves the selected draft and its reciprocal same-ID group from draft/ to active/, assigning the next available DEV number (highest existing number outside draft/ + 1) to every member, renaming the files, updating id, title, related references and links, and setting status: active. Pairing uses exact (project, id) metadata. Every group member must be explicitly configured and available, with unambiguous reciprocal references; incomplete groups block activation rather than activating a subset.
Drafts are committed DEV files with status: draft in devDir/draft/, and never reserve numbers: the draft/ folder is ignored by number suggestions, promotion and duplicate checks. Save/discard dirty source or affected editor buffers before applying. Markdown links are repaired within configured devDir trees only; docsRoot broadens number inventory, not lifecycle eligibility or repair scope.
For CLI usage, install Node.js 24 and run npm install -g markdown-utils, then mdutils --help. Preview initialization with mdutils init --project backend; add --yes to create the file, the default document types and the templates under docs/templates/ (existing files are never overwritten; --legacy writes the old configuration without types). Add --software (VS Code asks "Is this a software development project?") to also create docs/dev/{draft,active,done}/.gitkeep (existing folders are skipped) and enable requiresDevLifecycleFolders. In this checkout, use npm run cli -- --help. See the short CLI command guide. CLI mutations show a dry-run preview unless --yes is supplied.
Standalone CLI and agents
From this checkout, run npm run compile && npm link to make mdutils available on PATH. No VS Code process is required. The legacy node /absolute/path/to/dist/cli.js ... invocation remains supported.
mdutils --help
mdutils capabilities --json --root ../backend
mdutils create-dev "Shared feature" --projects backend,frontend,mobile --root ../backend --json
# Review the preview, then repeat with --yes.
mdutils create-dev "Shared feature" --projects backend,frontend,mobile --root ../backend --json --yes
# Create a paired draft instead; review before adding --yes.
mdutils create-dev "Future feature" --draft --projects backend,frontend --root ../backend --json
mdutils promote docs/dev/draft/DEV-0001-future-feature.md --root ../backend --json
All commands accept --json before or after the command. JSON mode emits exactly one object on stdout, pretty-printed with two-space indentation (including argument/configuration errors); diagnostics are fields, not interspersed text. The object spans multiple lines; parse the complete stdout as JSON rather than parsing each line separately. Use the executable directly for machine consumption: npm scripts may print their own banners.
The response has status (success, preview, or error), canonical command, numeric exitCode, and files (planned/destination { project, path } entries). Numbered operations include ticket; command-specific fields are under data. Link results include checkedLinks, brokenLinks, and unresolvedLinks. Lifecycle results include source/destination paths, IDs, and link-repair paths. Promotion retains the initiating member's fields, adds data.participants with project/old/new IDs and source/destination paths, and lists every destination in files with one shared ticket. Errors include error.code and error.message, with rollbackFailures for creation/lifecycle failures when applicable. File entries in an error response are intended targets, not proof they were created.
- Exit
0: success or successful preview.
- Exit
1: operation failure or broken/unresolved links (preserves links behavior).
- Exit
2: invalid arguments or configuration. Previously CLI errors generally exited 1; scripts should now handle this separate category. Human-readable output remains the default.
capabilities derives commands/options and document/template lists from the same definitions used by the CLI. It includes configured projects, roots, availability, and numbering settings. Without configuration it still returns static capabilities and an empty project list; malformed configuration returns an explicit error. This command does not scan documents or write files.
Previews never write or reserve numbers. DEV IDs are coordinated across every available configured related repository, even when a plan is created in only one selected repository. Creation rechecks availability under ordered repository locks and never overwrites documents. Concurrent requests may cause one caller to fail with a collision rather than silently allocate a duplicate; preview again and retry after checking the error. Paired operations use one ID across selected repositories and roll back only their own unchanged files if creation partially fails. Inspect remaining files and any rollbackFailures before retrying; never delete another agent's work. --dry-run cannot be combined with --yes, and unsupported/duplicate flags are rejected rather than ignored.
set-id-number FILE [--number N] assigns a manually chosen DEV number to a single document, fixing the filename, the leading DEV-xxxx/DEV-NNNN token in title, and frontmatter id (also available as the VS Code command Set ID Number). It prompts when --number is omitted (an error with --json), previews before --yes, rewrites links to the renamed file, and never touches paired documents. A number already used elsewhere requires --yes --allow-duplicate.
create-dev --draft (also create dev --draft) creates DEV files named DEV-0000-* in draft/; --number cannot be combined with --draft, and drafts are rejected for repositories without requiresDevLifecycleFolders. promote FILE uses the same group activation as Set as Active and has no number override. A manually chosen --number that already exists is previewed with a warning (data.duplicates, data.requiresDuplicateConfirmation in JSON); applying it requires --yes --allow-duplicate, and existing files are never overwritten.
Group activation is coordinated under repository locks, but is not crash-atomic across repositories. On an ordinary failure it restores removed drafts and unchanged operation-owned repairs/destinations. For incomplete rollback or interruption, inspect reported paths and Git diff, reconcile the original draft group using retained active copies or Git/editor history, then run mdutils links --json and check reciprocal references before previewing again. Changed files are never overwritten for recovery; no persistent workflow flag prevents a reconciled retry.
For Codex/Copilot integration, copy or link the CLI instruction section into each backend, frontend, and mobile repository's AGENTS.md; related-project configuration does not distribute instructions automatically. Do not assign DEV numbers manually, and always review a preview before applying with --yes.
Configurable document types
init seeds a types block in .markdownutils.jsonc and creates one Markdown template per type under docs/templates/ (existing files are never overwritten). After that the repository owns both: edit, remove, reorder or add your own types and templates. Each key is the frontmatter type value. The picker lists types as 01 - Implementation plan, 02 - Issue, … sorted by order, so you can type a number or text to filter.
| Type key |
Prefix |
Folder |
Use |
implementation-plan |
DEV |
docs/dev |
Plan and track implementation work, with the draft/active/done lifecycle |
issue |
ISS (legacy IID) |
docs/issues |
Bug, improvement or request |
brainstorming |
BST (legacy BID) |
docs/brainstorming |
Explore a topic and its options |
rfc |
RFC |
docs/rfcs |
Request for comments on a proposal |
adr |
ADR |
docs/adr |
Architectural decision record |
research |
RSC |
docs/research |
Investigation, findings and confidence |
tech-note |
none |
docs/tech-notes |
Short dated finding |
guide |
GDE (legacy GID) |
docs/guides |
Reusable instructions and procedures |
quickstart |
none |
docs/quickstarts |
Get something running in minutes |
runbook |
RBK |
docs/runbooks |
Operate or recover a system |
checklist |
none |
docs/checklists |
Repeatable task list |
gist |
none |
docs/gists |
Copy-and-paste commands and snippets |
meeting |
none |
docs/meetings |
Attendees and minutes |
note |
none |
docs/notes |
Informal standalone note |
"types": {
"issue": { "label": "Issue", "order": 20, "prefix": "ISS", "aliases": ["IID"], "dir": "docs/issues", "template": "docs/templates/template-issue.md", "statuses": ["draft", "open", "in-progress", "closed"] },
"tech-note": { "label": "Tech note", "order": 70, "dir": "docs/tech-notes", "template": "docs/templates/template-tech-note.md", "statuses": ["draft", "active"] }
}
prefix (3–4 uppercase letters) makes a type numbered; omit it for unnumbered types. aliases are legacy prefixes that stay recognized and share the number sequence.
statuses[0] is the initial status; filename (unnumbered only) defaults to {{slug}}; lifecycle: "dev" (at most one type) uses devDir and the draft/active/done flow.
- Templates are Markdown files with
{{title}} {{id}} {{date}} {{status}} {{project}} {{author}} {{slug}} placeholders. Unknown placeholders stay as written, and a missing or unreadable template falls back to a minimal frontmatter body with a warning.
- Type fields:
label (required), order, prefix, aliases, dir, template, statuses, filename, lifecycle and description. Unknown fields are rejected. Keys must be lowercase kebab-case, and prefixes (including aliases) must be unique.
- Create from the CLI with
mdutils create --type KEY "Title" --yes; mdutils capabilities --json lists the registry.
- Repositories without
types keep the legacy behavior (DEV, IID, ADR, BID, GID).
Migrating an existing repository
mdutils migrate previews, and --yes applies, adding the types block, creating missing templates, renaming BID- → BST-, IID- → ISS-, GID- → GDE- (same numbers) and repairing links and frontmatter IDs. It is idempotent and reports documents with unknown types. Use --keep-prefixes to keep the legacy prefixes. See ADR-0001.
Commands and navigation
New Markdown File lists the types configured in types (or the built-in legacy catalogue when a repository has none), plus README and Frontmatter conventions files. Documents are created from each type's template in its configured dir. DEV plans are created directly in devDir by default. Set requiresDevLifecycleFolders: true to use devDir/draft/, devDir/active/, and devDir/done/; the folder name matches the status value (draft, active, done). In flat mode, completion and reopening update frontmatter status in place between active and done. Number suggestions and duplicate checks include files directly in devDir as well as active/ and done/ (never draft/), even without related projects. Legacy repositories (no types block): ADR, Guide, Issue, and Brainstorming documents use their optional repository-relative adrDir, gidDir, iidDir, and bidDir destinations, respectively, or the folder selected in Explorer when the corresponding setting is missing or blank. Their next numbers are based on files in the chosen destination. Notes always use the selected Explorer folder. Run mdutils migrate to move to configurable types.
Create Agent Skill scaffolds .agents/skills/markdownutils/ at the selected workspace root. If the folder already exists, the command prompts for overwrite; confirming removes the existing folder and rewrites the scaffold.
Breaking changes (DEV-0016): the TMP prefix, numbering.reserveDraftNumbers, completed/, status: completed, and promote --number are removed; requiresDevActiveCompleted is renamed requiresDevLifecycleFolders (the old key is rejected). Existing files and legacy TMP drafts are not migrated. Each related project inherits the flag unless its relatedProjects entry overrides it.
Recursive documentation numbering
Set "docsRoot": "docs" to scan the entire documentation tree for DEV, GID, IID, ADR, and BID IDs, including nested, archived, done, hidden, and Git-ignored folders. Each prefix keeps its own sequence; suggestions use the highest filename ID plus one, and manual choices and final creation checks use the same scope.
The root is relative to its repository and controls numbering only. Creation destinations and DEV lifecycle/navigation eligibility do not change. For example, leave gidDir unset to create a guide in the right-clicked docs/guides/cloudflare folder while checking GIDs anywhere under docs. Generic CLI non-DEV numbered documents still go to devDir/active.
DEV coordination uses each available related repository's own scope. Set docsRoot explicitly in each relatedProjects entry to opt that checkout into recursive scanning; omitted related settings do not inherit the current repository's root and retain legacy DEV scanning. No related configuration files are loaded automatically. CLI capabilities reports each resolved docsRoot (or null) without scanning.
All numbered destinations, including devDir, must be inside the configured root after symlink resolution. The root must exist before numbering; create it or correct the configuration if a scan fails. Recursive numbering ignores all symlink entries, including directory, Markdown file, and broken links, without following or inspecting their targets. They do not reserve IDs or block commands; configure related repositories explicitly when their documents should participate in DEV coordination. Unreadable real directories produce explicit scan errors, never an empty/partial successful inventory.
Omitting docsRoot preserves the previous scan behavior described above. Initialization includes a commented opt-in example and never rewrites existing configs. Upgrade before adding this field, since older versions reject it. Existing documents are not renamed or renumbered. A collision after preview fails without overwriting; inspect the result, preview again, and retry.
Open Related Plan reads only structured relationships such as:
related:
- { project: "frontend", id: "DEV-0012" }
- { project: "mobile", id: "DEV-0041" }
It searches directly in devDir and in draft/, active/, and done/ under each named project's configured devDir, matches project and ID independently (IDs may differ between relationships), and presents all matches. Legacy string-only relationship entries are preserved but not navigable. If the target repository is unavailable or no file matches, the command reports the unresolved reference.
A configured vscodeProfile opens the selected document using the VS Code code command in that profile. If the CLI launch fails, Markdown Utils warns and opens the document in the current window.
Validate Links never writes. It scans Markdown beneath configured devDir roots and shows every broken or unresolved link, grouped by repository and file, in the Markdown Utils Link Validation Output channel. Reference links without a definition are unresolved.
Explorer menus use filenames as coarse filters. Commands validate the selected file, its metadata, folder, configuration, and operation eligibility at runtime. Lifecycle actions preview changes and link repairs before applying them.
Configuration and repository hygiene
Each repository uses one shared configuration: .markdownutils.jsonc (recommended, with line/block comments and trailing commas) or the existing strict .markdownutils.json. Existing JSON files need no migration. JSONC is not JSON5: keys and strings still need double quotes. Duplicate keys and syntax errors are rejected in both formats.
Optional local overrides in .markdownutils.local.jsonc or .markdownutils.local.json may change only paths and profile names for already-declared related projects. Either local format can accompany either shared format. These files are machine-specific and should not be committed. Ignore both local names and the lock directory in every configured repository:
.markdownutils.local.json
.markdownutils.local.jsonc
.markdownutils.lock/
Keep only one shared and one local file. If both alternatives for either role exist, commands report a conflict instead of choosing one silently. Merge any desired content manually, then remove or rename the extra file. A local override without a shared file is invalid; initialization can add the missing shared file without editing the override (which may still need correcting).
Drafts in devDir/draft/ are regular committed files; no .gitignore entry is needed or recommended. Do not ignore the full docs/dev/ tree unless that is your repository policy.
Link validation does not recurse through symlinked directories. Symlinked Markdown targets are accepted only when their resolved paths remain inside a configured repository; otherwise they are reported unresolved. Related repository and documentation-root paths are checked for symlink escapes.
Troubleshooting
- A related plan is missing: check the exact lowercase
project key, repository availability, and the configured devDir/draft/, devDir/active/, or devDir/done/ location. The filename ID and any frontmatter id/project values must agree with the relationship.
- A backend, frontend, or mobile link is unresolved: declare that repository under
relatedProjects, verify its checkout path and devDir, then rerun validation. Links outside configured roots and links reachable only through symlinked directories are not managed targets.
- Profile opening falls back to the current window: ensure the VS Code
code executable is on PATH and check the extension host's permissions to launch it.
- An Explorer action appears but rejects a file: visibility is deliberately coarse; the command performs stricter runtime checks and explains the ineligible file or location.
See setup for extension development and test instructions, and Markdown frontmatter conventions for document metadata rules.