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).

Technical Details

How It Works:

  1. User navigates to directory URL
  2. Plugin attempts to serve index.html
  3. Checks .pages for directory_index: true
  4. Calls Forgejo API to list contents
  5. Generates HTML listing page
  6. Serves and caches for 60 seconds

API Calls: Uses GET /api/v1/repos/{owner}/{repo}/contents/{path}

Performance Impact:

  • One additional API call when triggered
  • < 1ms generation time
  • 60-second caching reduces repeated calls
  • No impact on regular file serving

Mobile Responsiveness: Hides Type and Size columns on devices < 768px width, displays only Name column with icons.

Troubleshooting

Directory Listing Not Showing:

  • Verify directory_index: true in .pages
  • Check directory URL format
  • Confirm no index.html exists
  • Ensure directory has files
  • Validate YAML formatting

Empty Listing:

  • Directory may be truly empty
  • Hidden files (starting with .) may not display
  • Check if only subdirectories present

index.html Takes Precedence: Expected behavior—remove/rename index.html if directory listing needed.

Comparison with Other Solutions

vs. Apache Directory Index:

  • More modern design and mobile-responsive
  • Per-repository configuration
  • Color-coded icons
  • No column sorting yet
  • No date modified column

vs. Manual index.html:

  • Automatic and always current
  • Less maintenance required
  • Works at any directory depth
  • Lacks custom styling/branding options

Future Enhancements

  • Column sorting by name, size, type
  • Last modified date display
  • Search/filter functionality
  • Custom icons by file extension
  • Themeable design
  • Custom header/footer content
  • Bulk download (zip)