Directory Listings

Apache-style file browser for directories without an index.html file

Directory listings provide an Apache-style file browser for directories without an index.html file. This feature is disabled by default and can be enabled per-repository.

Overview

When enabled, displays a formatted HTML page showing all files and folders in a directory, similar to Apache’s directory indexing but with modern, responsive design.

When Are Directory Listings Shown?

Directory listings display when all conditions are met:

  1. ✅ directory_index: true in repository’s .pages file
  2. ✅ Directory URL requested (no file extension)
  3. ✅ No index.html exists in directory
  4. ✅ Directory exists and contains files

Features

Visual Design:

  • Modern interface with gradient header
  • Responsive layout (desktop, tablet, mobile)
  • Color-coded icons (yellow folders, blue files, gray back arrow)
  • Hover effects and readable typography

Functionality:

  • File information display (name, type, size)
  • Parent directory navigation
  • Clickable entries for files/folders
  • Human-readable file sizes
  • Breadcrumb path showing location
  • Sorted entries via API order

Performance:

  • 60-second caching
  • Fast API calls via Forgejo directory API
  • Lightweight, pure Go implementation

Configuration

Enable:

enabled: true
directory_index: true

Disable (default):

enabled: true
directory_index: false

Usage Examples

Documentation Repository - nested folders with mixed index.html presence File Archive - public downloads and assets Mixed Content - some directories with index, others without

What Users See

  • Title: “Index of /path/to/directory”
  • Breadcrumb navigation
  • Table with Name, Type, Size columns
  • Clickable parent directory link
  • Footer attribution to Forgejo

Security Considerations

⚠️ All files in directories without index.html become visible when enabled.

Recommended Practices:

  • ✅ Public documentation, open source downloads, resource libraries
  • ❌ Private documents, sensitive filenames, backups, configuration files

Combine with Password Protection:

enabled: true
directory_index: true
password: your-sha256-hash-here

Limitations

Profile Sites (.profile Repository): Directory listings don’t work for profile site directories due to URL structure interpretation (file extensions distinguish profile files from repository names).

Workaround: Create a regular repository instead, or use custom domains (which work normally).