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
• Force overwrite of existing output files
• Configurable depth, file size limits, ignore patterns
• Optional upload to Proton Drive after generating output

Build

go build -o dirmd .

Usage

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

# Overwrite existing output file
dirmd -o output.md ~/repos/myproject -f

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

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

# Generate and upload to Proton Drive (default: /my-files/md/<filename>)
dirmd -o output.md ~/repos/myproject --proton-drive

# Generate and upload to a specific remote path
dirmd -o output.md ~/repos/myproject --proton-drive --drive-path /my-files/docs/api.md

Flags

Flag	Description	Default
-o, --output	Output markdown file path (required)
-a, --append	Append to existing output file	false
-f, --force	Overwrite existing output file (non-append mode)	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
--proton-drive	Upload output to Proton Drive after writing locally	false
--drive-path	Full remote path on Proton Drive (e.g. /my-files/md/report.md)	/my-files/md/<filename>

Proton Drive Integration

dirmd can optionally upload the generated markdown file to Proton Drive using the Proton Drive CLI. The upload is performed only when --proton-drive is passed. Without it, dirmd behaves exactly as before — no Proton Drive dependency is required.

Prerequisites

1. Install the Proton Drive CLI — see the official guide for download and installation instructions.
2. Authenticate by running proton-drive auth login.
3. Ensure proton-drive is in your PATH.

If the CLI is not installed or you are not logged in, dirmd will report the error to stderr and exit with a non-zero code. The local markdown file is still written successfully before the upload is attempted.

Upload Behavior

• Default remote path: /my-files/md/<filename> where <filename> is the basename of the local output file.
• Override with --drive-path /my-files/custom/report.md (full path including filename).
• Existing remote files are overwritten (--conflict-strategy replace).
• The local markdown file is always written before the upload is attempted.

For full documentation on the Proton Drive CLI, including installation, authentication, and troubleshooting, refer to the official Proton Drive CLI support page.

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

# Generate, then upload to default remote location
dirmd -o docs.md ~/repos/project --proton-drive

# Generate, then upload to a custom remote location
dirmd -o docs.md ~/repos/project --proton-drive --drive-path /my-files/projects/docs.md

# Overwrite existing local file and upload to Drive
dirmd -o docs.md ~/repos/project -f --proton-drive

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.