proj2md

proj2md is a command-line tool that generates a comprehensive Markdown document for any project directory. It traverses files, extracts structure and contents, and outputs a self-descriptive .md file ideal for LLM ingestion or static documentation.

Features

• Recursive directory traversal with extension filtering
• Optional ASCII tree view of the project structure
• Automatic table of contents with anchors
• YAML front-matter with project metadata (name, version, author, date)
• Modes:
  • light: only tree + existing README
  • full: complete extraction of all files
• List of dependencies from pyproject.toml or poetry
• Customizable snippet length (--max-snippet-lines)
• Exclusion patterns for files/folders (--exclude)
• Easy installation via pip and entry-point proj2md

Installation

Requires Python 3.13 or higher.

Install from PyPI:

pip install proj2md

Or install locally from source:

git clone https://github.com/yourusername/proj2md.git
cd proj2md
pip install .

Usage

Basic usage (note that the actual file will be prefixed with generated_):

Note: regardless of the name provided via --output-file, the output file will be prefixed with generated_ to avoid self-inclusion.

Basic usage:

proj2md --input-dir ./my_project --output-file ./project.md

Available options:

--input-dir, -i PATH        Root directory (default: .)
--output-file, -o FILE      Output Markdown file (default: project.md)
--with-tree / --no-tree     Include project tree (default: with-tree)
--with-deps / --no-deps     Include dependencies list (default: with-deps)
--extensions, -e EXT1,EXT2  Comma-separated extensions (default: .py,.md,.yaml,.json)
--mode [light|full]         Extraction mode (default: full)
--max-snippet-lines N       Limit lines per file snippet
--exclude, -x PAT1,PAT2     Comma-separated ignore patterns

Examples

Full extraction with tree and dependencies:

proj2md -i ./src -o docs/project_full.md --with-tree --with-deps --mode full

Light mode (only tree + README):

proj2md -i ./src -o docs/project_light.md --no-deps --no-tree --mode light

Development

A Taskfile.yaml is provided to simplify common development workflows. Install the Task runner (task command), then run:

# Setup development environment (venv, dependencies, pre-commit)
task setup-dev

# Run the test suite
task run-tests

# Run code formatting and linting
task linter

# Clean build artifacts and cache
task clean

To list all available tasks:

task --list

Contributing

See CONTRIBUTING.md for guidelines on contributing.

Code of Conduct

This project adheres to the Contributor Covenant.

License

This project is licensed under the MIT License - see the LICENSE file for details.