markdown-context-pack

Pack Markdown and MDX files into a single context document.

npx markdown-context-pack . -o context.md

mdctx is a local CLI for preparing repository docs before sharing them with an LLM, a reviewer, or another tool that works best with one input file. It preserves file boundaries, includes a file index, estimates token usage, and keeps the output as plain Markdown.

Why

Project context is usually already written down. It lives in README.md, docs/, ADRs, changelogs, runbooks, specs, and notes. The problem is that those files are scattered.

mdctx collects them without trying to interpret or rewrite them. The result is a predictable context.md file that can be reviewed, committed, attached, pasted, or generated again.

Install

Run without installing:

npx markdown-context-pack . -o context.md

Install globally:

npm install -g markdown-context-pack

Then use the shorter command:

mdctx . -o context.md

Usage

Pack the current directory:

mdctx . -o context.md

Pack a docs folder:

mdctx docs -o docs-context.md

Preview the files that would be included:

mdctx . --dry-run

Limit the output to a rough token budget:

mdctx docs --max-tokens 120000 -o docs-context.md

Generate stable output for diffs:

mdctx docs --no-generated-at -o docs-context.md

Pack one file:

mdctx README.md

Ignore extra paths for one run:

mdctx . --ignore archive,private-notes.md -o public-context.md

Ignore Rules

mdctx skips common repository noise by default, including .git, node_modules, dist, build caches, and generated context files.

For project-specific rules, add .mdctxignore next to the files you are packing:

drafts/
private-notes.md
*.internal.md
docs/archive/

Blank lines and # comments are ignored. Plain paths and simple *, **, and ? globs are supported.

Disable .mdctxignore for a single run:

mdctx . --no-ignore-file

Output

The generated file contains:

• pack metadata
• an index of included files
• rough token counts
• omitted files when --max-tokens excludes them
• each source file inside a fenced Markdown block

Example:

# Markdown Context Pack: docs

## Pack Metadata

- Source: `docs`
- Included files: 3
- Omitted files: 1
- Approx tokens: 18420

## File Index

- 1. `README.md` - Project Docs - 1200 tokens
- 2. `guide/setup.md` - Setup - 5400 tokens

## Documents

### 1. `README.md`

```markdown
# Project Docs
...
```

CLI

mdctx [path] [options]

Options:
  -o, --output <file>       Write the pack to a file instead of stdout
  --max-tokens <number>     Include whole files until this rough token budget is hit
  --heading <text>          Override the generated H1
  --ignore <paths>          Comma-separated extra files or folders to ignore
  --extensions <list>       Comma-separated extensions
  --no-ignore-file          Do not read .mdctxignore
  --no-generated-at         Omit the generated timestamp
  --dry-run                 Print the planned file list without writing the pack
  -q, --quiet               Hide success messages when writing to a file
  -v, --version             Print the version
  -h, --help                Print help

Default extensions are .md, .markdown, and .mdx.

Development

npm install
npm test
npm run smoke

License

MIT