-----BEGIN PGP SIGNED MESSAGE-----
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

Prerequisites

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

CurrentPath

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

Customization

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.

HeaderName
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
ReadmeName
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
IndexOptions
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 :

FancyIndexing
This turns on fancy indexing of directories. Obviously.
SuppressHTMLPreamble

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.

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

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.

VersionSort
The VersionSort keyword causes files containing version numbers to sort in a natural way.
IndexIgnore
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
</Directory>
# 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"
</Directory>

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 !

-----BEGIN PGP SIGNATURE-----
Comment: GPGTools - http://gpgtools.org

iQIcBAEBCAAGBQJW5eRIAAoJEBeKS2x6xuR7jRgP/RARJnBj4w6ttTJfOfofgg2J
EGz2ga607b9D6c9QRQ357BdgytdXNth9eSUAe3hfSHNqpSfm2jULsfQuLocpPg3R
6LVXO1vYpD27WpgSX95hEza2RwPV5urRd84ZueThuwGl0XLaLvKd4UNWDHgm+0PQ
uzu5lDl4+xBVHKOW2cnn1TLoXkUN1apuZwjI90ssjUWbf9NOn4PPlVp80bmLUJDs
TWjT8NfiTA4ZvfkY+KhnAQFLlkda0cY/0Q7pKf1Glz4HULG10CLwyoY8n3fXakPR
4kB2JL1QmaKrcIP0FVnf3E8kiCulbSaYbTobzE7K916NRg7ih9xYe2FW3L5O0gk2
Np9DrArqUCLrc/y1b7vnsn/EuIYLMxu7BOt8ZlRl1wrNlxH3ZeYYOH4+pZVSEfFW
AsbAGQLh8Kxxzkp+a7v/AaL8F/XNIl3AtQt1vNfZFewAeLrGFkB76esaqowvKrNy
LL7AEzsxRF42hzhloVLGvBId4lrNpK20BExu7JLgxYulU1vIhxII9rb/kwoenFlJ
kA1TnczaPqE4Ew/Zj6iDLnQWFrsdiusTekFeT2g1DGvmJ4o5u4MK/jH5VC5wDaVC
8KTrz0CAA+EUctzq4jPQXOkClpAPTYxGNRuEW2Gu5OCsT09ZMBn9Dbs/nFMZVPe2
+R/w35QaJ2xjNUl5UVL4
=2G7y
-----END PGP SIGNATURE-----

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

Resources

10 last blog posts

Related to this article

blog comments powered by Disqus