dirmd

Generate markdown documentation from directory structure.

Features

• Recursive directory traversal
• Tree visualization (standard tree command format)
• Full file contents with syntax-highlighted code blocks
• Filters dotfiles, binaries, and blacklisted extensions
• Append mode for single files or directories
• Configurable depth, file size limits, ignore patterns

Build

go build -o dirmd .

Usage

# Create new documentation
dirmd -o output.md ~/repos/myproject

# Append a single file
dirmd -a -i README.md -o existing.md

# Append another directory
dirmd -a ~/repos/anotherproject -o existing.md

Flags

Flag	Description	Default
-o, --output	Output markdown file path (required)
-a, --append	Append to existing output file	false
-i, --input-file	Single file input (append mode only)
--max-size	Max file size in bytes	524288
--max-depth	Max directory recursion depth	20
--ignore	Additional ignore patterns (glob)
--extensions	Additional file extensions to skip

Examples

# Custom depth and size limit
dirmd -o output.md ~/repos/project --max-depth 5 --max-size 262144

# Ignore specific directories
dirmd -o output.md ~/repos/project --ignore __pycache__ --ignore .venv

# Skip additional file extensions
dirmd -o output.md ~/repos/project --extensions .log --extensions .tmp

Output Format

Produces markdown with:

1. Absolute path as H1 header
2. Directory tree (indented with 4 spaces per level)
3. All text files with content in code blocks
4. Language detection from file extensions

Example output structure:

# /home/user/repos/myproject

## Directory Tree

myproject/
├── cmd/
│   └── main.go
└── internal/
    └── config.go

## Contents

### ./cmd/main.go

```go
package main

func main() {}
```

Note: Uses tilde fences (~~~) internally to avoid conflicts with nested backticks in source files.