Dir2md is a powerful tool designed to transform your codebase into optimized Markdown blueprints, effectively catering to the requirements of Large Language Models (LLMs). By analyzing directory structures, it generates comprehensive documentation that intelligently samples content while controlling token budgets, enhancing the context for AI-assisted development.

Key Features

• Smart Content Sampling: Use head/tail sampling with configurable token budgets, ensuring relevant information is highlighted.
• Duplicate Detection: Employs SimHash-based deduplication to minimize noise and enhance clarity.
• Security First: Offers enhanced secret masking capabilities, including complete PEM blocks and AWS keys, ensuring sensitive information is protected.
• Multiple Output Modes: Choose from reference, summary, or full inline content to suit your documentation needs.
• Highly Configurable: Extensive filtering and customization options for tailored outputs.
• Developer Friendly: Default raw mode provides complete visibility into the code, allowing developers to maintain control.

Quick Online Demo

Experience Dir2md instantly in your browser through the demo available on Hugging Face Spaces. This demo allows users to convert any GitHub repository into Markdown while offering real-time directory structure analysis and downloadable markdown blueprints, all without installation.

Basic Usage

Dir2md can be easily invoked through the command line, offering various functionalities:

# Generate project blueprint in raw mode
dir2md .

# Generate with enhanced security masking
dir2md . --masking basic

# Generate with manifest for CI/CD
dir2md . --emit-manifest --no-timestamp

# Token-optimized for LLM context
dir2md . --budget-tokens 4000 --preset iceberg

Sample Output

When you generate a directory tree, the output will look something like this:

# Project Blueprint

- Root: `/path/to/project`
- Generated: `2025-09-08 12:30:15`
- Preset: `raw`
- LLM mode: `inline`
- Estimated tokens (prompt): `6247`

## Directory Tree
[Complete file structure]

## Statistics
| Metric | Value |
|--------|-------|
| Total files | 42 |
| Estimated tokens | 6247 |

## File Contents
[Intelligently sampled content...]

Presets Available

• raw: Full content inclusion, ideal for development and code reviews.
• iceberg: A balanced sampling approach suitable for general documentation.
• pro: Advanced optimization for larger projects requiring LLM context.

Open-Core Model

Dir2md adopts an open-core model, providing key features for free while offering advanced functionalities in a commercial package. Free features include:

• Complete directory analysis
• Token optimization and sampling
• Enhanced security masking with specific patterns
• All output modes and presets

Documentation

For comprehensive guidance, explore the following:

• Feature Comparison - Detailed breakdown of OSS versus Pro features.
• Current Status - Overview of implemented features.
• Usage Examples - Practical examples to assist users.

Community and Contributions

Dir2md encourages community involvement, allowing users to contribute and discuss enhancements through GitHub Issues and Discussions. This project aims to streamline the documentation process, addressing common pain points associated with traditional methods in AI-supported environments.