1======================== 2Nginx Fancy Index module 3======================== 4 5.. image:: https://travis-ci.com/aperezdc/ngx-fancyindex.svg?branch=master 6 :target: https://travis-ci.com/aperezdc/ngx-fancyindex 7 :alt: Build Status 8 9.. contents:: 10 11The Fancy Index module makes possible the generation of file listings, like 12the built-in `autoindex <http://wiki.nginx.org/NginxHttpAutoindexModule>`__ 13module does, but adding a touch of style. This is possible because the module 14allows a certain degree of customization of the generated content: 15 16* Custom headers. Either local or stored remotely. 17* Custom footers. Either local or stored remotely. 18* Add you own CSS style rules. 19* Allow choosing to sort elements by name (default), modification time, or 20 size; both ascending (default), or descending. 21 22This module is designed to work with Nginx_, a high performance open source web 23server written by `Igor Sysoev <http://sysoev.ru>`__. 24 25 26Requirements 27============ 28 29CentOS 7 30~~~~~~~~ 31 32For users of the `official stable <https://www.nginx.com/resources/wiki/start/topics/tutorials/install/>`__ Nginx repository, `extra packages repository with dynamic modules <https://www.getpagespeed.com/redhat>`__ is available and fancyindex is included. 33 34Install directly:: 35 36 yum install https://extras.getpagespeed.com/redhat/7/x86_64/RPMS/nginx-module-fancyindex-1.12.0.0.4.1-1.el7.gps.x86_64.rpm 37 38Alternatively, add extras repository first (for future updates) and install the module:: 39 40 yum install nginx-module-fancyindex 41 42Then load the module in `/etc/nginx/nginx.conf` using:: 43 44 load_module "modules/ngx_http_fancyindex_module.so"; 45 46Other platforms 47~~~~~~~~~~~~~~~ 48 49In most other cases you will need the sources for Nginx_. Any version starting 50from the 0.8 series should work. 51 52In order to use the ``fancyindex_header_`` and ``fancyindex_footer_`` directives 53you will also need the `ngx_http_addition_module <https://nginx.org/en/docs/http/ngx_http_addition_module.html>`_ 54built into Nginx. 55 56 57Building 58======== 59 601. Unpack the Nginx_ sources:: 61 62 $ gunzip -c nginx-?.?.?.tar.gz | tar -xvf - 63 642. Unpack the sources for the fancy indexing module:: 65 66 $ gunzip -c nginx-fancyindex-?.?.?.tar.gz | tar -xvf - 67 683. Change to the directory which contains the Nginx_ sources, run the 69 configuration script with the desired options and be sure to put an 70 ``--add-module`` flag pointing to the directory which contains the source 71 of the fancy indexing module:: 72 73 $ cd nginx-?.?.? 74 $ ./configure --add-module=../nginx-fancyindex-?.?.? \ 75 [--with-http_addition_module] [extra desired options] 76 77 Since version 0.4.0, the module can also be built as a 78 `dynamic module <https://www.nginx.com/resources/wiki/extending/converting/>`_, 79 using ``--add-dynamic-module=…`` instead and 80 ``load_module "modules/ngx_http_fancyindex_module.so";`` 81 in the configuration file 82 834. Build and install the software:: 84 85 $ make 86 87 And then, as ``root``:: 88 89 # make install 90 915. Configure Nginx_ by using the modules' configuration directives_. 92 93 94Example 95======= 96 97You can test the default built-in style by adding the following lines into 98a ``server`` section in your Nginx_ configuration file:: 99 100 location / { 101 fancyindex on; # Enable fancy indexes. 102 fancyindex_exact_size off; # Output human-readable file sizes. 103 } 104 105 106Themes 107~~~~~~ 108 109The following themes demonstrate the level of customization which can be 110achieved using the module: 111 112* `Theme <https://github.com/TheInsomniac/Nginx-Fancyindex-Theme>`__ by 113 `@TheInsomniac <https://github.com/TheInsomniac>`__. Uses custom header and 114 footer. 115* `Theme <https://github.com/Naereen/Nginx-Fancyindex-Theme>`__ by 116 `@Naereen <https://github.com/Naereen/>`__. Uses custom header and footer, the 117 header includes search field to filter by filename using JavaScript. 118* `Theme <https://github.com/fraoustin/Nginx-Fancyindex-Theme>`__ by 119 `@fraoustin <https://github.com/fraoustin>`__. Responsive theme using 120 Material Design elements. 121* `Theme <https://github.com/alehaa/nginx-fancyindex-flat-theme>`__ by 122 `@alehaa <https://github.com/alehaa>`__. Simple, flat theme based on 123 Bootstrap 4 and FontAwesome. 124 125 126Directives 127========== 128 129fancyindex 130~~~~~~~~~~ 131:Syntax: *fancyindex* [*on* | *off*] 132:Default: fancyindex off 133:Context: http, server, location 134:Description: 135 Enables or disables fancy directory indexes. 136 137fancyindex_default_sort 138~~~~~~~~~~~~~~~~~~~~~~~ 139:Syntax: *fancyindex_default_sort* [*name* | *size* | *date* | *name_desc* | *size_desc* | *date_desc*] 140:Default: fancyindex_default_sort name 141:Context: http, server, location 142:Description: 143 Defines sorting criterion by default. 144 145fancyindex_directories_first 146~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 147:Syntax: *fancyindex_directories_first* [*on* | *off*] 148:Default: fancyindex_directories_first on 149:Context: http, server, location 150:Description: 151 If enabled (default setting), groups directories together and sorts them 152 before all regular files. If disabled, directories are sorted together with files. 153 154fancyindex_css_href 155~~~~~~~~~~~~~~~~~~~ 156:Syntax: *fancyindex_css_href uri* 157:Default: fancyindex_css_href "" 158:Context: http, server, location 159:Description: 160 Allows inserting a link to a CSS style sheet in generated listings. The 161 provided *uri* parameter will be inserted as-is in a ``<link>`` HTML tag. 162 The link is inserted after the built-in CSS rules, so you can override the 163 default styles. 164 165fancyindex_exact_size 166~~~~~~~~~~~~~~~~~~~~~ 167:Syntax: *fancyindex_exact_size* [*on* | *off*] 168:Default: fancyindex_exact_size on 169:Context: http, server, location 170:Description: 171 Defines how to represent file sizes in the directory listing; either 172 accurately, or rounding off to the kilobyte, the megabyte and the 173 gigabyte. 174 175fancyindex_name_length 176~~~~~~~~~~~~~~~~~~~~~~ 177:Syntax: *fancyindex_name_length length* 178:Default: fancyindex_name_length 50 179:Context: http, server, location 180:Description: 181 Defines the maximum file name length limit in bytes. 182 183fancyindex_footer 184~~~~~~~~~~~~~~~~~ 185:Syntax: *fancyindex_footer path* [*subrequest* | *local*] 186:Default: fancyindex_footer "" 187:Context: http, server, location 188:Description: 189 Specifies which file should be inserted at the foot of directory listings. 190 If set to an empty string, the default footer supplied by the module will 191 be sent. The optional parameter indicates whether the *path* is to be 192 treated as an URI to load using a *subrequest* (the default), or whether 193 it refers to a *local* file. 194 195.. note:: Using this directive needs the ngx_http_addition_module_ built 196 into Nginx. 197 198.. warning:: When inserting custom header/footer a subrequest will be 199 issued so potentially any URL can be used as source for them. Although it 200 will work with external URLs, only using internal ones is supported. 201 External URLs are totally untested and using them will make Nginx_ block 202 while waiting for the subrequest to complete. If you feel like external 203 header/footer is a must-have for you, please 204 `let me know <mailto:aperez@igalia.com>`__. 205 206fancyindex_header 207~~~~~~~~~~~~~~~~~ 208:Syntax: *fancyindex_header path* [*subrequest* | *local*] 209:Default: fancyindex_header "" 210:Context: http, server, location 211:Description: 212 Specifies which file should be inserted at the head of directory listings. 213 If set to an empty string, the default header supplied by the module will 214 be sent. The optional parameter indicates whether the *path* is to be 215 treated as an URI to load using a *subrequest* (the default), or whether 216 it refers to a *local* file. 217 218.. note:: Using this directive needs the ngx_http_addition_module_ built 219 into Nginx. 220 221fancyindex_show_path 222~~~~~~~~~~~~~~~~~~~~ 223:Syntax: *fancyindex_show_path* [*on* | *off*] 224:Default: fancyindex_show_path on 225:Context: http, server, location 226:Description: 227 Whether to output or not the path and the closing </h1> tag after the header. 228 This is useful when you want to handle the path displaying with a PHP script 229 for example. 230 231.. warning:: This directive can be turned off only if a custom header is provided 232 using fancyindex_header. 233 234fancyindex_show_dotfiles 235~~~~~~~~~~~~~~~~~~~~ 236:Syntax: *fancyindex_show_dotfiles* [*on* | *off*] 237:Default: fancyindex_show_dotfiles off 238:Context: http, server, location 239:Description: 240 Whether to list files that are proceeded with a dot. Normal convention is to 241 hide these. 242 243fancyindex_ignore 244~~~~~~~~~~~~~~~~~ 245:Syntax: *fancyindex_ignore string1 [string2 [... stringN]]* 246:Default: No default. 247:Context: http, server, location 248:Description: 249 Specifies a list of file names which will be not be shown in generated 250 listings. If Nginx was built with PCRE support strings are interpreted as 251 regular expressions. 252 253fancyindex_hide_symlinks 254~~~~~~~~~~~~~~~~~~~~~~~~ 255:Syntax: *fancyindex_hide_symlinks* [*on* | *off*] 256:Default: fancyindex_hide_symlinks off 257:Context: http, server, location 258:Description: 259 When enabled, generated listings will not contain symbolic links. 260 261fancyindex_hide_parent_dir 262~~~~~~~~~~~~~~~~~~~~~~~~ 263:Syntax: *fancyindex_hide_parent_dir* [*on* | *off*] 264:Default: fancyindex_hide_parent_dir off 265:Context: http, server, location 266:Description: 267 When enabled, it will not show parent directory. 268 269fancyindex_localtime 270~~~~~~~~~~~~~~~~~~~~ 271:Syntax: *fancyindex_localtime* [*on* | *off*] 272:Default: fancyindex_localtime off 273:Context: http, server, location 274:Description: 275 Enables showing file times as local time. Default is “off” (GMT time). 276 277fancyindex_time_format 278~~~~~~~~~~~~~~~~~~~~~~ 279:Syntax: *fancyindex_time_format* string 280:Default: fancyindex_time_format "%Y-%b-%d %H:%M" 281:Context: http, server, location 282:Description: 283 Format string used for timestamps. The format specifiers are a subset of 284 those supported by the `strftime <https://linux.die.net/man/3/strftime>`_ 285 function, and the behavior is locale-independent (for example, day and month 286 names are always in English). The supported formats are: 287 288 * ``%a``: Abbreviated name of the day of the week. 289 * ``%A``: Full name of the day of the week. 290 * ``%b``: Abbreviated month name. 291 * ``%B``: Full month name. 292 * ``%d``: Day of the month as a decimal number (range 01 to 31). 293 * ``%e``: Like ``%d``, the day of the month as a decimal number, but a 294 leading zero is replaced by a space. 295 * ``%F``: Equivalent to ``%Y-%m-%d`` (the ISO 8601 date format). 296 * ``%H``: Hour as a decimal number using a 24-hour clock (range 00 297 to 23). 298 * ``%I``: Hour as a decimal number using a 12-hour clock (range 01 to 12). 299 * ``%k``: Hour (24-hour clock) as a decimal number (range 0 to 23); 300 single digits are preceded by a blank. 301 * ``%l``: Hour (12-hour clock) as a decimal number (range 1 to 12); single 302 digits are preceded by a blank. 303 * ``%m``: Month as a decimal number (range 01 to 12). 304 * ``%M``: Minute as a decimal number (range 00 to 59). 305 * ``%p``: Either "AM" or "PM" according to the given time value. 306 * ``%P``: Like ``%p`` but in lowercase: "am" or "pm". 307 * ``%r``: Time in a.m. or p.m. notation. Equivalent to ``%I:%M:%S %p``. 308 * ``%R``: Time in 24-hour notation (``%H:%M``). 309 * ``%S``: Second as a decimal number (range 00 to 60). 310 * ``%T``: Time in 24-hour notation (``%H:%M:%S``). 311 * ``%u``: Day of the week as a decimal, range 1 to 7, Monday being 1. 312 * ``%w``: Day of the week as a decimal, range 0 to 6, Monday being 0. 313 * ``%y``: Year as a decimal number without a century (range 00 to 99). 314 * ``%Y``: Year as a decimal number including the century. 315 316 317.. _nginx: https://nginx.org 318 319.. vim:ft=rst:spell:spelllang=en: 320