folder2md4llms 0.5.8

A tool to convert folder structures and file contents into markdown for LLMs

folder2md4llms

folder2md4llms is a configurable tool that converts a repository's contents into a single, LLM-friendly Markdown file. It supports various file formats and provides options for content condensing and filtering.

✨ Key Features

• Smart Condensing: Automatically condenses code to fit within a specified token or character limit without crude truncation.
• Document Conversion: Converts PDF, DOCX, XLSX, and other document formats into text.
• Binary File Analysis: Provides intelligent descriptions for images, archives, and other binary files.
• Highly Configurable: Use a folder2md.yaml file or command-line options to customize the output.
• Parallel Processing: Uses multi-threading for processing multiple files concurrently.
• Advanced Filtering: Uses .gitignore-style patterns to exclude files and directories.

🚀 Installation

⚠️ Requirements: Python 3.11 or higher is required.

Using Python 3.8-3.10? Install the legacy version: pipx install folder2md4llms==0.2.0

# Check Python version first
python --version  # Must be 3.11+

# Using pipx (recommended)
pipx install folder2md4llms

# Or using pip
pip install folder2md4llms

# Verify installation
folder2md --help

Note: Package name is folder2md4llms, command is folder2md

Basic Usage

# Process the current directory and save to output.md
folder2md .

# Process a specific directory and set a token limit
folder2md /path/to/repo --limit 80000t

# Copy the output to the clipboard
folder2md /path/to/repo --clipboard

# Generate a .folder2md_ignore file
folder2md --init-ignore

For a full list of commands and options, see the CLI Reference or run folder2md --help.

🚨 Troubleshooting

Common Issues

"No matching distribution found for folder2md"

• Use the correct package name: folder2md4llms (not folder2md)

"Requires Python >=3.11" or incompatible Python version

• Check your Python version: python --version
• If you have Python 3.8-3.10, use the legacy version: pipx install folder2md4llms==0.2.0
• To upgrade Python, see: https://www.python.org/downloads/

"Command 'folder2md' not found"

• Ensure pipx is installed: pip install pipx
• Try: python -m folder2md4llms .

Platform-Specific Issues

Windows: Use WSL2 (Recommended)

For Windows users, we recommend using WSL2 (Windows Subsystem for Linux) for the best experience:

# Install WSL2 (run in PowerShell as Administrator)
wsl --install -d Ubuntu-22.04

# Then follow the Linux installation instructions in WSL2

This provides better compatibility and performance compared to native Windows installation.

Getting Help

• Command help: folder2md --help
• Version check: folder2md --version
• Alternative: python -m folder2md4llms --help (works without installation)
• Report issues: GitHub Issues
• Discussions: GitHub Discussions

🔧 Configuration

You can configure folder2md4llms by creating a folder2md.yaml file in your repository's root directory. This allows you to set advanced options and define custom behavior.

For more details, see the CLI Reference.

🛠️ Development

Interested in contributing? Get started with these simple steps:

# Clone the repository
git clone https://github.com/henriqueslab/folder2md4llms.git
cd folder2md4llms

# Set up the development environment
make setup

# See all available commands
make help

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For more information, see the Contributing Guidelines.

📖 Documentation

• CLI Reference - Complete command-line reference
• Contributing Guidelines - How to contribute to the project
• Changelog - Version history and changes

📦 Distribution Channels

• PyPI: folder2md4llms - Python package

📄 License

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