Output Formats

promptprep supports multiple output formats to suit different needs. This page explains the available formats and how to use them.

Overview

You can specify the output format using the --format option:

promptprep --format FORMAT [other options]

Where FORMAT is one of the available formats described below.

Available Formats

Plain Text (Default)

The default format is plain text, which is simple and works everywhere:

promptprep --format plain -o output.txt
# or simply
promptprep -o output.txt

Example output:

# Code Aggregation - my_project

## Directory Structure

project/
├── src/
│   ├── main.py
│   └── utils.py
└── tests/
    └── test_main.py

## File: src/main.py

def main():
    print("Hello, world!")

if __name__ == "__main__":
    main()

## File: src/utils.py

def helper_function():
    return "I'm helping!"

Markdown

The Markdown format creates GitHub-friendly output with proper code blocks and syntax highlighting:

promptprep --format markdown -o output.md

Example output:

# Code Aggregation - my_project

## Directory Structure

```
project/
├── src/
│   ├── main.py
│   └── utils.py
└── tests/
    └── test_main.py
```

## File: src/main.py

```python
def main():
    print("Hello, world!")

if __name__ == "__main__":
    main()
```

## File: src/utils.py

```python
def helper_function():
    return "I'm helping!"
```

HTML

The HTML format generates a complete webpage with basic styling:

promptprep --format html -o output.html

This creates a self-contained HTML file with CSS styling that can be opened in any web browser.

Highlighted

The highlighted format adds full syntax highlighting with colors to make your code more readable:

promptprep --format highlighted -o output.html

This requires the optional pygments package:

pip install promptprep[highlighting]

The result is an HTML file with syntax highlighting based on the file type.

Custom

The custom format lets you design your own output format using a template file:

promptprep --format custom --template-file my_template.txt -o output.txt

See Custom Templates for details on creating and using custom templates.

Format-Specific Features

Line Numbers

You can add line numbers to the code in the output with the --line-numbers option:

promptprep --format markdown --line-numbers -o output_with_lines.md

Example output with line numbers:

## File: src/main.py

```python
1  def main():
2      print("Hello, world!")
3
4  if __name__ == "__main__":
5      main()
```

This works with all formats except custom (where you need to handle line numbers in your template).

Format Detection from Output File

promptprep can automatically detect the desired format based on the output file extension:

promptprep -o output.md  # Uses markdown format
promptprep -o output.html  # Uses html format

The mapping is: - .md: markdown - .html: html - .htm: html - Other extensions: plain

You can override this by explicitly specifying the format:

promptprep --format markdown -o output.txt  # Uses markdown format despite .txt extension

Choosing the Right Format

Each format has its strengths and is suited for different use cases:

Format	Strengths	Best For
plain	Simple, works everywhere, no dependencies	Quick snapshots, universal compatibility
markdown	Good readability, works on GitHub, syntax highlighting	Sharing on GitHub, documentation, AI model prompts
html	Interactive, can be opened in browsers	Sharing with non-technical users, documentation
highlighted	Best readability, full syntax highlighting	Code reviews, presentations, documentation
custom	Complete flexibility	Specialized outputs, integration with other tools

Best Practices

Match Format to Audience: Choose a format that works best for your intended audience.
Consider File Size: HTML and highlighted formats may produce larger files.
Use Markdown for AI Models: When sharing with AI models like GPT-4, the markdown format works best.
Add Line Numbers for Reference: Use --line-numbers when you need to reference specific lines.
Combine with Metadata: Add --metadata to include useful statistics about your codebase.

Examples

For AI Model Assistance

promptprep -d ./my_project --format markdown --metadata --count-tokens -c

This creates markdown output with metadata and token count, and copies it to your clipboard for pasting into an AI chat.

For Documentation

promptprep -d ./src --format highlighted -o documentation.html

This creates a syntax-highlighted HTML file that can be shared as documentation.

For Code Reviews

promptprep -d ./feature_branch --diff main_branch.txt --format highlighted --line-numbers -o review.html

This creates a syntax-highlighted HTML file with line numbers showing what changed between branches.

For Quick Reference

promptprep -d . --summary-mode --format plain -o quick_reference.txt

This creates a plain text file with only function/class signatures and docstrings for quick reference.

Troubleshooting

If you encounter issues with output formats:

Missing Dependencies: For highlighted format, ensure you have installed the highlighting extra.
Format Not Recognized: Check that you’re using one of the supported format names.
Custom Template Issues: Verify that your custom template file exists and contains valid placeholders.
Line Numbers Not Showing: Ensure you’re using the --line-numbers option with a compatible format.