Contents
- Requirements
- Building
- Example
- Directives
- fancyindex
- fancyindex_default_sort
- fancyindex_case_sensitive
- fancyindex_directories_first
- fancyindex_css_href
- fancyindex_exact_size
- fancyindex_footer
- fancyindex_header
- fancyindex_show_path
- fancyindex_show_dotfiles
- fancyindex_ignore
- fancyindex_hide_symlinks
- fancyindex_hide_parent_dir
- fancyindex_localtime
- fancyindex_time_format
The Fancy Index module makes possible the generation of file listings, like the built-in autoindex module does, but adding a touch of style. This is possible because the module allows a certain degree of customization of the generated content:
- Custom headers, either local or stored remotely.
- Custom footers, either local or stored remotely.
- Add your own CSS style rules.
- Allow choosing to sort elements by name (default), modification time, or size; both ascending (default), or descending.
This module is designed to work with Nginx, a high performance open source web server written by Igor Sysoev.
For users of the official stable Nginx repository, extra packages repository with dynamic modules is available and fancyindex is included.
Install repository configuration, then the module package:
yum -y install https://extras.getpagespeed.com/release-latest.rpm yum -y install nginx-module-fancyindex
Then load the module in /etc/nginx/nginx.conf using:
load_module "modules/ngx_http_fancyindex_module.so";
Users can install Nginx on macOS with MacPorts; fancyindex is included:
sudo port install nginx
In most other cases you will need the sources for Nginx. Any version starting from the 0.8 series should work.
In order to use the fancyindex_header_ and fancyindex_footer_ directives
you will also need the ngx_http_addition_module
built into Nginx.
Unpack the Nginx sources:
$ gunzip -c nginx-?.?.?.tar.gz | tar -xvf -
Unpack the sources for the fancy indexing module:
$ gunzip -c nginx-fancyindex-?.?.?.tar.gz | tar -xvf -
Change to the directory which contains the Nginx sources, run the configuration script with the desired options and be sure to put an
--add-moduleflag pointing to the directory which contains the source of the fancy indexing module:$ cd nginx-?.?.? $ ./configure --add-module=../nginx-fancyindex-?.?.? \ [--with-http_addition_module] [extra desired options]
Since version 0.4.0, the module can also be built as a dynamic module, using
--add-dynamic-module=…instead andload_module "modules/ngx_http_fancyindex_module.so";in the configuration fileBuild and install the software:
$ make
And then, as
root:# make install
Configure Nginx by using the modules' configuration directives.
You can test the default built-in style by adding the following lines into
a server section in your Nginx configuration file:
location / {
fancyindex on; # Enable fancy indexes.
fancyindex_exact_size off; # Output human-readable file sizes.
}
The following themes demonstrate the level of customization which can be achieved using the module:
- Theme by @TheInsomniac. Uses custom header and footer.
- Theme by @Naereen. Uses custom header and footer. The header includes a search field to filter by file name using JavaScript.
- Theme by @fraoustin. Responsive theme using Material Design elements.
- Theme by @alehaa. Simple, flat theme based on Bootstrap 4 and FontAwesome.
| Syntax: | fancyindex [on | off] |
|---|---|
| Default: | fancyindex off |
| Context: | http, server, location |
| Description: | Enables or disables fancy directory indexes. |
| Syntax: | fancyindex_default_sort [name | size | date | name_desc | size_desc | date_desc] |
|---|---|
| Default: | fancyindex_default_sort name |
| Context: | http, server, location |
| Description: | Defines sorting criterion by default. |
| Syntax: | fancyindex_case_sensitive [on | off] |
|---|---|
| Default: | fancyindex_case_sensitive on |
| Context: | http, server, location |
| Description: | If enabled (default setting), sorting by name will be case-sensitive. If disabled, case will be ignored when sorting by name. |
| Syntax: | fancyindex_directories_first [on | off] |
|---|---|
| Default: | fancyindex_directories_first on |
| Context: | http, server, location |
| Description: | If enabled (default setting), groups directories together and sorts them before all regular files. If disabled, directories are sorted together with files. |
| Syntax: | fancyindex_css_href uri |
|---|---|
| Default: | fancyindex_css_href "" |
| Context: | http, server, location |
| Description: | Allows inserting a link to a CSS style sheet in generated listings. The
provided uri parameter will be inserted as-is in a <link> HTML tag.
The link is inserted after the built-in CSS rules, so you can override the
default styles. |
| Syntax: | fancyindex_exact_size [on | off] |
|---|---|
| Default: | fancyindex_exact_size on |
| Context: | http, server, location |
| Description: | Defines how to represent file sizes in the directory listing: either accurately, or rounding off to the kilobyte, the megabyte and the gigabyte. |
| Syntax: | fancyindex_footer path [subrequest | local] |
|---|---|
| Default: | fancyindex_footer "" |
| Context: | http, server, location |
| Description: | Specifies which file should be inserted at the foot of directory listings. If set to an empty string, the default footer supplied by the module will be sent. The optional parameter indicates whether the path is to be treated as a URI to load using a subrequest (the default), or whether it refers to a local file. |
Note
Using this directive needs the ngx_http_addition_module built into Nginx.
Warning
When inserting custom a header/footer, a subrequest will be issued so potentially any URL can be used as source for them. Although it will work with external URLs, only using internal ones is supported. External URLs are totally untested and using them will make Nginx block while waiting for the subrequest to complete. If you feel like external header/footer is a must-have for you, please let me know.
| Syntax: | fancyindex_header path [subrequest | local] |
|---|---|
| Default: | fancyindex_header "" |
| Context: | http, server, location |
| Description: | Specifies which file should be inserted at the head of directory listings. If set to an empty string, the default header supplied by the module will be sent. The optional parameter indicates whether the path is to be treated as a URI to load using a subrequest (the default), or whether it refers to a local file. |
Note
Using this directive needs the ngx_http_addition_module built into Nginx.
| Syntax: | fancyindex_show_path [on | off] |
|---|---|
| Default: | fancyindex_show_path on |
| Context: | http, server, location |
| Description: | Whether or not to output the path and the closing </h1> tag after the header. This is useful when you want to handle the path displaying with a PHP script for example. |
Warning
This directive can be turned off only if a custom header is provided using fancyindex_header.
| Syntax: | fancyindex_show_dotfiles [on | off] |
|---|---|
| Default: | fancyindex_show_dotfiles off |
| Context: | http, server, location |
| Description: | Whether to list files that are preceded with a dot. Normal convention is to hide these. |
| Syntax: | fancyindex_ignore string1 [string2 [... stringN]] |
|---|---|
| Default: | No default. |
| Context: | http, server, location |
| Description: | Specifies a list of file names which will not be shown in generated listings. If Nginx was built with PCRE support, strings are interpreted as regular expressions. |
| Syntax: | fancyindex_hide_symlinks [on | off] |
|---|---|
| Default: | fancyindex_hide_symlinks off |
| Context: | http, server, location |
| Description: | When enabled, generated listings will not contain symbolic links. |
| Syntax: | fancyindex_hide_parent_dir [on | off] |
|---|---|
| Default: | fancyindex_hide_parent_dir off |
| Context: | http, server, location |
| Description: | When enabled, it will not show the parent directory. |
| Syntax: | fancyindex_localtime [on | off] |
|---|---|
| Default: | fancyindex_localtime off |
| Context: | http, server, location |
| Description: | Enables showing file times as local time. Default is “off” (GMT time). |
| Syntax: | fancyindex_time_format string |
|---|---|
| Default: | fancyindex_time_format "%Y-%b-%d %H:%M" |
| Context: | http, server, location |
| Description: | Format string used for timestamps. The format specifiers are a subset of those supported by the strftime function, and the behavior is locale-independent (for example, day and month names are always in English). The supported formats are:
|