s3-genindex/docs/DETAILS.md

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

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

Using Go Install

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

Command Line Options

Usage: s3-genindex [OPTIONS] [directory]

  -d, --dir-append          append output file to directory href
  -f, --filter string       only include files matching glob (default "*")
  -i, --include-hidden      include dot hidden files
  -o, --output-file string  custom output file (default "index.html")
  -r, --recursive           recursively process nested dirs
  -v, --verbose             verbosely list every processed file
  -x, --exclude-regex string exclude files matching regular expression
  --top-dir string          top folder from which to start generating indexes

Usage Examples

Basic Usage

# 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

# Process directory tree recursively
s3-genindex -r

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

File Filtering

# Include only Python files
s3-genindex --filter "*.py"

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

# Include hidden files
s3-genindex -i

Advanced Usage

# 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 -rv --dir-append /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

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:

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

Code Quality

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

# Ensure read permissions on target directory
chmod +r /path/to/directory

Large Directories

# Use verbose mode to monitor progress
s3-genindex -v /large/directory

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

Memory Usage

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

Debug Mode

Enable verbose output to see detailed processing:

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