Your First Conversion¶

Let's walk through converting your first project with Folder2MD4LLMs. This guide will show you the basic workflow and introduce key concepts.

Basic Conversion¶

The simplest way to use Folder2MD4LLMs is to run it on a directory:

# Convert current directory
folder2md .

# Convert specific directory
folder2md /path/to/your/project

# Specify output file
folder2md . --output my-project.md

Example Walkthrough¶

Let's say you have a simple Python project:

my-python-app/
├── src/
│   ├── __init__.py
│   ├── main.py
│   └── utils.py
├── tests/
│   └── test_main.py
├── README.md
├── requirements.txt
└── setup.py

Step 1: Basic Conversion¶

cd my-python-app
folder2md .

This creates output.md containing your entire project structure and file contents.

Step 2: Review the Output¶

Open output.md to see:

# Folder2MD4LLMs Output

## Repository Structure

my-python-app/ ├── src/ │ ├── init.py │ ├── main.py │ └── utils.py ├── tests/ │ └── test_main.py ├── README.md ├── requirements.txt └── setup.py

## File Contents

### README.md
[Content of your README file]

### src/main.py
```python
[Content of your main.py file]

...

### Step 3: Add Smart Condensing

For larger projects, use smart condensing to fit within token limits:

```bash
folder2md . --token-limit 80000 --smart-condensing

This ensures the output fits within most LLM context windows while preserving important code structure.

Understanding the Output¶

Repository Structure¶

Every conversion starts with a tree view of your project structure, helping you and the LLM understand the organization.

File Contents¶

Files are presented in a logical order: 1. Documentation (README, docs) 2. Configuration (package.json, requirements.txt) 3. Source code (organized by importance) 4. Tests (if included)

Smart Filtering¶

By default, Folder2MD4LLMs respects .gitignore patterns and skips: - Binary files (unless analysis is enabled) - Large files (>1MB by default) - Common ignore patterns (node_modules, pycache, etc.)

Common Options¶

Output Control¶

# Specify output file
folder2md . --output project-summary.md

# Control output format
folder2md . --format markdown

# Include file statistics
folder2md . --stats

Content Control¶

# Set maximum file size (in bytes)
folder2md . --max-file-size 512000

# Exclude specific patterns
folder2md . --exclude-pattern "*.log" --exclude-pattern "tmp/**"

# Include only specific patterns
folder2md . --include-pattern "src/**/*.py" --include-pattern "*.md"

Processing Options¶

# Enable parallel processing
folder2md . --parallel

# Show progress
folder2md . --verbose

# Dry run (see what would be processed)
folder2md . --dry-run

Working with Different Project Types¶

Python Projects¶

# Focus on source code
folder2md . --include-pattern "src/**/*.py" --include-pattern "*.py" --include-pattern "*.md"

# Include configuration
folder2md . --include-pattern "**/*.py" --include-pattern "requirements.txt" --include-pattern "setup.py"

JavaScript/Node.js Projects¶

# Exclude node_modules (automatic) and focus on source
folder2md . --include-pattern "src/**/*.js" --include-pattern "src/**/*.ts" --include-pattern "*.json"

# Include documentation
folder2md . --include-pattern "**/*.{js,ts,jsx,tsx,md,json}"

Documentation Projects¶

# Include all documentation formats
folder2md . --include-docs --include-pattern "**/*.{md,rst,txt,pdf,docx}"

Next Steps¶

Now that you've performed your first conversion, you might want to:

Learn More Options¶

# See all available options
folder2md --help

# Get help for specific commands
folder2md convert --help

Create a Configuration File¶

For repeated use, create a folder2md.yaml file:

# folder2md.yaml
output: project-summary.md
token_limit: 80000
smart_condensing: true

include_patterns:
  - "src/**/*.py"
  - "*.md"
  - "requirements.txt"

exclude_patterns:
  - "tests/**"
  - "*.log"

Then run simply:

folder2md .

Explore Advanced Features¶

Configuration - Learn about YAML configuration files
Smart Condensing - Understand intelligent code compression
Document Conversion - Convert PDFs and Office documents
Binary Analysis - Analyze images and archives

Tips for Success¶

Start Small¶

Begin with a small project or subdirectory to understand the output format and options.

Use Dry Run¶

The --dry-run flag shows what files would be processed without creating output:

folder2md . --dry-run --verbose

Check Token Counts¶

Use --stats to see token and character counts:

folder2md . --stats

Use the output to refine your include/exclude patterns:

# First pass - see what's included
folder2md . --dry-run

# Refine patterns
folder2md . --exclude-pattern "docs/build/**" --include-pattern "docs/source/**"

Common Patterns¶

Code Review Preparation¶

folder2md . --token-limit 100000 --smart-condensing --exclude-pattern "tests/**"

Documentation Generation¶

folder2md . --include-docs --include-pattern "**/*.{md,rst,py}" --exclude-pattern "**/__pycache__/**"

Project Analysis¶

folder2md . --binary-analysis --stats --output project-analysis.md

You're now ready to convert your projects efficiently! Move on to the Quick Reference for a handy command cheat sheet.