Metadata-Version: 2.4
Name: directory-tree-html
Version: 0.2.0
Summary: Generate a searchable single-page Element Plus directory tree with file previews.
Project-URL: Repository, https://github.com/suqingdong/directory-tree-html
Project-URL: Issues, https://github.com/suqingdong/directory-tree-html/issues
Keywords: directory,tree,html,preview,cli,element-plus
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: Jinja2>=3.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"

# directory-tree-html

Generate a searchable, single-page HTML directory tree with file previews.
Built with Click, Jinja2, Vue 3, and the Element Plus Tree component.

Requires **Python 3.10 or later**.

## Features

- Expandable folders with distinct file and folder icons.
- Case-insensitive search across names, paths, file types, extensions, and MIME types.
- Highlighted matches with automatic expansion of matching paths.
- Click-to-preview support for text, code, images, PDF, audio, and video.
- Configurable hidden-file handling, glob exclusions, and preview size limits.
- Optional symlink traversal with cycle detection.

## Installation

```bash
python -m pip install directory-tree-html
```

## Quick Start

```bash
tree-html-generator ./my-project -o tree.html --title "Project Files"
```

Open `tree.html` in your browser to browse the directory snapshot.

You can also run the tool as a Python module:

```bash
python -m directory_tree_html ./my-project -o tree.html
```

### Command-Line Options

| Option | Description | Default |
| --- | --- | --- |
| `DIRECTORY` | Directory to scan (required) | - |
| `-o, --output` | Output HTML path; parent directories are created automatically | `directory_tree.html` |
| `--title` | Page title | `Directory Tree Preview` |
| `--include-hidden` | Include dot-prefixed files and folders | Disabled |
| `--follow-symlinks` | Follow symbolic links with cycle detection | Disabled |
| `--exclude GLOB` | Exclude by name or relative path; repeatable | None |
| `--max-preview-bytes` | Maximum embedded bytes per file; `0` disables previews | `262144` (256 KiB) |
| `--version` | Show the version | - |
| `-h, --help` | Show help | - |

### Examples

```bash
# Include hidden files and exclude common generated directories.
tree-html-generator . -o tree.html --include-hidden --exclude .git --exclude __pycache__ --exclude .venv --exclude build --exclude dist

# Exclude file patterns. Quote globs to prevent shell expansion.
tree-html-generator ./my-project -o tree.html --exclude "*.pyc" --exclude "*.tmp"

# Generate the tree without embedding file contents.
tree-html-generator ./my-project -o tree.html --max-preview-bytes 0
```

## Python API

```python
from directory_tree_html import generate_tree_html

result = generate_tree_html(
    "./my-project",
    output="tree.html",
    title="Project Files",
    excludes=["__pycache__", "*.pyc"],
    max_preview_bytes=256 * 1024,
)

print(result.output)           # Absolute output path
print(result.stats)            # Scan statistics
print(result.payload["tree"])  # Serializable tree data
```

## Notes

- Search uses literal substring matching, ignores case, and trims surrounding whitespace. It searches names and metadata, not file contents. Clearing the search restores the full tree.
- Vue and Element Plus are loaded from a CDN, so an internet connection is required to open the page. The HTML is not fully offline.
- Paths and previewable file contents are embedded in the HTML. Review the output before sharing it, or use exclusions and disable previews to avoid exposing sensitive data.
- Files exceeding the preview limit are not embedded. PDF and media previews depend on browser support.
- The output is a snapshot; regenerate it after source files change. Generated HTML uses UTF-8 encoding and LF line endings.
