Hash: SHA256

Improve the default look and make it integrate seamlessly to your website

When I recently had the need of conveniently presenting and sharing files, and not wanting to use Dropbox for this purpose because it wouldn’t fit perfectly with the look of this website, I searched and found a way of customizing the default Apache directory index. Here is how I proceeded.

This tutorial uses configuration directives available with version 2.2 of Apache, and as the Apache foundation recently announced version 2.4.1 - I don’t know if it’ll work. I didn’t tryed.

Without customization

Look how sad a default directory index looks:

  • Sad looking Apache directory index


For this, there is only one little thing you should care, is that module that we are going to use (mod_autoindex) is successfully loaded into your apache configuration. To do so, have a look in your httpd configuration files, and a similar line should be present :

LoadModule autoindex_module libexec/apache22/mod_autoindex.so


If you are like me, using a static content publishing system and do want to customize a directory index, you might want to still display the path that you are currently browsing in the file repository. As the website is statically generated, there is no way to enumerate the content of the directory, with all its content. You then need to use mod_include that will enable server side includes, which will modify the page with according values.

Using mod_include to display other informations on your webpage is completely outside the scope of this tutorial, but you should be able to follow the documentation to achieve what you want to do.

Ensure that mod_include is loaded :

LoadModule include_module libexec/apache22/mod_include.so

Just above the file listing, I’ll include the following to tell apache to show the currently browsed URI:

<!--#echo var="REQUEST_URI"-->

In the apache configuration, relative to the folder that you want to enhance the browsing experience (then inside the Directory directive) put the following directives (that will tell Apache to process server side includes) :

    AddType text/html .shtml
    AddOutputFilter INCLUDES .shtml
    Options Indexes Includes


These are the directives that we will use to insert file at the top of the generated page, append at the end, change the default Index behaviour, and hide our SHTML files.

Description:Name of the file that will be inserted at the top of the index listing
Syntax:HeaderName filename
Context:server config, virtual host, directory, .htaccess
Description:Name of the file that will be inserted at the end of the index listing
Syntax:ReadmeName filename
Context:server config, virtual host, directory, .htaccess
Description:Various configuration settings for directory indexing
Syntax:IndexOptions [+|-]<var>option</var> [[+|-]<var>option</var>] ...
Default:By default, no options are enabled.
Context:server config, virtual host, directory, .htaccess

We are going to use the following IndexOptions options :

This turns on fancy indexing of directories. Obviously.

If the directory actually contains a file specified by the HeaderName directive, the module usually includes the contents of the file after a standard HTML preamble (<html>, <head>, et cetera). The SuppressHTMLPreamble option disables this behaviour, causing the module to start the display with the header file contents. The header file must contain appropriate HTML instructions in this case. If there is no header file, the preamble is generated as usual.

The XHTML keyword forces mod_autoindex to emit XHTML 1.0 code instead of HTML 3.2.
Pretty clear
Like I love
Grows the column containing the filename to the necessary width.

This returns the Last-Modified and ETag values for the listed directory in the HTTP header. It is only valid if the operating system and file system return appropriate stat() results. Some Unix systems do so, as do OS2’s JFS and Win32’s NTFS volumes. OS2 and Win32 FAT volumes, for example, do not. Once this feature is enabled, the client or proxy can track changes to the list of files when they perform a HEAD request. Note some operating systems correctly track new and removed files, but do not track changes for sizes or dates of the files within the directory. Changes to the size or date stamp of an existing file will not update the Last-Modified header on all Unix platforms. If this is a concern, leave this option disabled.

The VersionSort keyword causes files containing version numbers to sort in a natural way.
Description:Adds to the list of files to hide when listing a directory
Syntax:IndexIgnore <var>file</var> [<var>file</var>] ...
Default:IndexIgnore "."
Context:server config, virtual host, directory, .htaccess

Putting everything together

Finally, here is the configuration when everything is set up using the configuration directives:

<Directory "/usr/local/www/bkraft/files">
    RewriteEngine Off
    AddType text/html .shtml
    AddOutputFilter INCLUDES .shtml
    Options Indexes Includes
    IndexOptions FancyIndexing SuppressHTMLPreamble XHTML IconsAreLinks
    IndexOptions FoldersFirst NameWidth=* TrackModified VersionSort
    IndexIgnore .??* *~ *# HEADER* README.shtml RCS CVS *,v *,
    HeaderName /files/HEADER.shtml
    ReadmeName /files/README.shtml
    AllowOverride none
    Options All Indexes FollowSymLinks MultiViews 
    Order allow,deny
    Allow from all
# This is because I wanted a different content for this specific directory.
<Directory "/usr/local/www/bkraft/files/VMware Appliances/Owncloud-3.0.0">
    ReadmeName "/files/VMware Appliances/Owncloud-3.0.0/README.shtml"

And here is how it looks …

  • Wow looking Apache directory index

I hope that you’ll find this very little tutorial useful, and if you have any questions, just leave me a message !

Comment: GPGTools - http://gpgtools.org


Hint: To validate signature, please view page source and copy html code between BEGIN PGP Signed message and END PGP Signature anchors.

Created the 2012-02-23

Share this

Article content


10 last blog posts

Related to this article

blog comments powered by Disqus