directory_listing: easy, CSS-styled, Apache-like directory listings for Sinatra.

Description

directory_listing is a Sinatra plugin that generates Apache-like directory listings. It was designed to be:

1. Easy to use and configure
2. Style-able with CSS
3. Able to replicate all the features of Apache's directory listings including sorting

directory_listing also includes a number of configuration options - see the Options section below.

Install

For regular use:

(sudo) gem install directory_listing

Or from source:

bundle install
rake install

Usage

list() will return HTML, so the following is a complete Sinatra app that will provide a directory listing of whatever path you navigate to and let you view any file that is served directly:

require 'sinatra'
require 'sinatra/directory_listing'

get '*' do |path|
  if File.exist?(File.join(settings.public_folder, path))
    if File.directory?(File.join(settings.public_folder, path))
      list()
    else
      send_file File.join(settings.public_folder, path)
    end
  else
    not_found
  end
end

not_found do
  'Try again.'
end

Options

Options are passed in a hash:

list({
  :stylesheet => "stylesheets/styles.css",
  :readme => "<a>Welcome!</a>"
})

Available options:

• stylesheet - a stylesheet to style the generated directory listing with, relative to your public_folder
• readme - an HTML string that will be appended at the footer of the generated directory listing
• should_list_invisibles - whether the directory listing should include invisibles (dotfiles) - true or false, defaults to false
• should_show_file_exts - whether the directory listing should show file extensions - true or false, defaults to true
• smart_sort - whether sorting should ignore "[Tt]he " at the beginning of filenames - true or false, defaults to true
• last_modified_format - format for last modified date - defaults to %Y-%m-%d %H:%M:%S
• filename_truncate_length - length to truncate file names to - integer, defaults to 40

Styling

It's pretty easy to figure out how to style directory_listing by looking at the source, but here are some gotchas:

• Every file is a <td> element in a table. Directories will have a class of dir and regular files will have a class of file.
• You can style the "File" column with this CSS:

table tr > td:first-child { 
  text-align: left;
}

• "Last modified" column:

table tr > td:first-child + td { 
  text-align: left;
}

• "Size" column:

table tr > td:first-child + td + td { 
  text-align: left;
}

• The navigation bar is in a div called nav and consists of links embedded in h1 tags:

div.nav h1, div.nav a {
  font-size: 16px;
  font-weight: 600;
}

Getting Help

The best way to report a bug or feature request is to open an issue on GitHub.

Additionally, I'd love to hear your feedback about directory_listing through Twitter or email.

Changelog

Here are the latest commits.

Contributing

1. Fork it
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes (remember to include a test!): git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Create new Pull Request

Note:

Out of the box, the test suite will fail, as one of the tests tries to sort via mtime, and git doesn't preserve mtimes. You'll want to touch those files in the following order to make them pass - 2k.dat, 3k.dat, 1k.dat.

License

directory_listing is licensed under the MIT license. See the LICENSE file for details.