# s3-genindex - Detailed Documentation

## Overview

s3-genindex is a Go rewrite of the original Python genindex.py script. It generates HTML directory listings with file type icons, responsive design, and dark mode support.

## Features

- **File Type Detection**: Recognizes 100+ file extensions with appropriate icons
- **Responsive Design**: Works on desktop and mobile devices
- **Dark Mode**: Automatic dark mode support based on system preferences
- **Recursive Processing**: Generate indexes for entire directory trees
- **File Filtering**: Include/exclude files by pattern or regex
- **Symlink Support**: Special handling for symbolic links
- **Custom Output**: Configurable output filename
- **Breadcrumb Navigation**: Parent directory navigation

## Installation

### From Source

```bash
git clone https://git.ipng.ch/ipng/s3-genindex.git
cd s3-genindex
make build
```

### Using Go Install

```bash
go install git.ipng.ch/ipng/s3-genindex/cmd/s3-genindex@latest
```

## Command Line Options

```
Usage: s3-genindex [OPTIONS] [directory]

  -d	append output file to directory href
  -f string
    	only include files matching glob (default "*")
  -i	include dot hidden files
  -o string
    	custom output file (default "index.html")
  -r	recursively process nested dirs
  -v	verbosely list every processed file
  -x string
    	exclude files matching regular expression
```

## Usage Examples

### Basic Usage

```bash
# Generate index.html in current directory
s3-genindex

# Generate index for specific directory
s3-genindex /path/to/directory

# Generate with custom output filename
s3-genindex -o listing.html
```

### Recursive Processing

```bash
# Process directory tree recursively
s3-genindex -r

# Process recursively with verbose output
s3-genindex -rv /var/www
```

### File Filtering

```bash
# Include only Python files
s3-genindex -f "*.py"

# Exclude build artifacts and dependencies
s3-genindex -x "(build|dist|node_modules|__pycache__|\\.tmp)"

# Include hidden files
s3-genindex -i
```

### Advanced Usage

```bash
# Recursive with custom output and exclusions
s3-genindex -r -o index.html -x "(\.git|\.svn|node_modules)" /var/www

# Verbose processing with directory appending
s3-genindex -r -v -d /home/user/public
```

## File Type Support

The tool recognizes and provides appropriate icons for:

### Programming Languages
- Go (`.go`)
- Python (`.py`, `.pyc`, `.pyo`)
- JavaScript/TypeScript (`.js`, `.ts`, `.json`)
- HTML/CSS (`.html`, `.htm`, `.css`, `.scss`)
- Shell scripts (`.sh`, `.bash`, `.bat`, `.ps1`)
- SQL (`.sql`)

### Documents
- PDF (`.pdf`)
- Text/Markdown (`.txt`, `.md`, `.markdown`)
- Office documents (`.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`)
- CSV (`.csv`)

### Media Files
- Images (`.jpg`, `.png`, `.gif`, `.svg`, `.webp`)
- Videos (`.mp4`, `.mov`, `.avi`, `.webm`)
- Audio (`.mp3`, `.wav`, `.flac`, `.ogg`)

### Archives
- Zip files (`.zip`, `.tar`, `.gz`, `.7z`, `.rar`)
- Package files (`.deb`, `.rpm`, `.dmg`, `.pkg`)

### System Files
- Certificates (`.crt`, `.pem`, `.key`)
- Configuration files
- License files (LICENSE, README)

## HTML Output Features

### Responsive Design
- Mobile-friendly layout
- Collapsible columns on small screens
- Touch-friendly navigation

### Dark Mode
- Automatic detection of system preference
- Clean dark color scheme
- Proper contrast ratios

### File Information
- File sizes in human-readable format
- Last modified timestamps
- File type icons
- Sorting (directories first, then alphabetical)

### Navigation
- Parent directory links
- Breadcrumb-style navigation
- Clickable file/directory entries

## Project Structure

```
s3-genindex/
├── cmd/s3-genindex/        # Main application
│   ├── main.go            # CLI entry point
│   └── main_test.go       # CLI tests
├── internal/indexgen/      # Core library
│   ├── indexgen.go        # Main functionality
│   ├── indexgen_test.go   # Unit tests
│   └── integration_test.go # Integration tests
├── docs/                  # Documentation
├── Makefile              # Build automation
├── README.md             # Quick start guide
└── go.mod               # Go module definition
```

## Development

### Building

```bash
make build          # Build binary
make test           # Run tests
make test-coverage  # Run tests with coverage
make check          # Run all checks (fmt, vet, lint, test)
```

### Testing

The project includes comprehensive tests:

- **Unit tests**: Test individual functions and utilities
- **Integration tests**: Test complete directory processing workflows
- **Template tests**: Verify HTML template generation
- **CLI tests**: Test command-line argument parsing

Run tests with:

```bash
make test                    # Basic test run
make test-coverage          # With coverage report
go test -v ./...           # Verbose output
go test -short ./...       # Skip integration tests
```

### Code Quality

```bash
make fmt      # Format code
make vet      # Vet for issues
make lint     # Run golangci-lint (if installed)
make check    # Run all quality checks
```

## Configuration

No configuration files are needed. All options are provided via command-line arguments.

### Environment Variables

The tool respects standard Go environment variables:
- `GOOS` and `GOARCH` for cross-compilation
- `GOPATH` and `GOBIN` for installation paths

## Comparison with Original

This Go version provides the same functionality as the original Python script with these improvements:

### Performance
- Faster execution, especially for large directory trees
- Lower memory usage
- Single binary deployment

### Maintenance
- Comprehensive test suite
- Type safety
- Better error handling
- Structured codebase

### Compatibility
- Identical HTML output
- Same command-line interface
- Cross-platform binary

## Troubleshooting

### Common Issues

**Permission Errors**
```bash
# Ensure read permissions on target directory
chmod +r /path/to/directory
```

**Large Directories**
```bash
# Use verbose mode to monitor progress
s3-genindex -v /large/directory

# Exclude unnecessary files
s3-genindex -x "(\.git|node_modules|__pycache__)"
```

**Memory Usage**
```bash
# Process directories individually for very large trees
for dir in */; do s3-genindex "$dir"; done
```

### Debug Mode

Enable verbose output to see detailed processing:

```bash
s3-genindex -v /path/to/debug
```

## License

Licensed under the Apache License 2.0. See original Python script for full license text.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run `make check` to ensure code quality
5. Submit a pull request

## Changelog

### v1.0.0
- Initial Go rewrite
- Complete feature parity with Python version
- Comprehensive test suite
- Modern Go project structure