ngx-fancyindex

by aperezdc

aperezdc / ngx-fancyindex

Fancy indexes module for the Nginx web server

458 Stars 91 Forks Last release: 8 months ago (v0.4.4) Other 212 Commits 16 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

========================

Nginx Fancy Index module

.. image:: https://travis-ci.org/aperezdc/ngx-fancyindex.svg?branch=master :target: https://travis-ci.org/aperezdc/ngx-fancyindex :alt: Build Status

.. contents::

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 you 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 
_.

Requirements

CentOS 7 ~~~~~~~~

For users of the

official stable 
__ Nginx repository,
extra packages repository with dynamic modules 
__ is available and fancyindex is included.

Install directly::

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

Alternatively, add extras repository first (for future updates) and install the module::

yum install nginx-module-fancyindex

Then load the module in

/etc/nginx/nginx.conf
using::

loadmodule "modules/ngxhttpfancyindexmodule.so";

Other platforms ~~~~~~~~~~~~~~~

In most other cases you will need the sources for Nginx_. Any version starting from the 0.7 series onwards will work. Note that the modules might compile with versions in the 0.6 series by applying

nginx-0.6-support.patch
, but this is unsupported (YMMV).

In order to use the

fancyindex_header_
and
fancyindex_footer_
directives you will also need the
ngx_http_addition_module 
_ built into Nginx.

Building

  1. Unpack the Nginx_ sources::

    $ gunzip -c nginx-?.?.?.tar.gz | tar -xvf -

  2. Unpack the sources for the fancy indexing module::

    $ gunzip -c nginx-fancyindex-?.?.?.tar.gz | tar -xvf -

  3. Change to the directory which contains the Nginx_ sources, run the configuration script with the desired options and be sure to put an

    --add-module
    flag pointing to the directory which contains the source of the fancy indexing module::

    $ cd nginx-?.?.? $ ./configure --add-module=../nginx-fancyindex-?.?.? \ [--with-httpadditionmodule] [extra desired options]

Since version 0.4.0, the module can also be built as a

dynamic module 
, using
--add-dynamic-module=…
instead and ``load
module "modules/ngxhttpfancyindex_module.so";`` in the configuration file
  1. Build and install the software::

    $ make

And then, as

root
::
# make install
  1. Configure Nginx_ by using the modules' configuration directives_.

Example

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. fancyindexexactsize off; # Output human-readable file sizes. }

Themes ~~~~~~

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 search field to filter by filename using JavaScript.
  • Theme 
    __ by
    @fraoustin 
    __. Responsive theme using Material Design elements.
  • Theme 
    __ by
    @alehaa 
    __. Simple, flat theme based on Bootstrap 4 and FontAwesome.

Directives

fancyindex ~~~~~~~~~~ :Syntax: fancyindex [on | off] :Default: fancyindex off :Context: http, server, location :Description: Enables or disables fancy directory indexes.

fancyindexdefaultsort ~~~~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexdefaultsort [name | size | date | name_desc | size_desc | date_desc] :Default: fancyindexdefaultsort name :Context: http, server, location :Description: Defines sorting criterion by default.

fancyindexdirectoriesfirst ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexdirectoriesfirst [on | off] :Default: fancyindexdirectoriesfirst 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.

fancyindexcsshref ~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexcsshref uri :Default: fancyindexcsshref "" :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

 HTML tag.
  The link is inserted after the built-in CSS rules, so you can override the
  default styles.

fancyindexexactsize ~~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexexactsize [on | off] :Default: fancyindexexactsize 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.

fancyindexnamelength ~~~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexnamelength length :Default: fancyindexnamelength 50 :Context: http, server, location :Description: Defines the maximum file name length limit in bytes.

fancyindexfooter ~~~~~~~~~~~~~~~~~ :Syntax: *fancyindexfooter path* :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.

.. note:: Using this directive needs the ngxhttpadditionmodule built into Nginx.

.. warning:: When inserting custom 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 
__.

fancyindexheader ~~~~~~~~~~~~~~~~~ :Syntax: *fancyindexheader path* :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.

.. note:: Using this directive needs the ngxhttpadditionmodule built into Nginx.

fancyindexshowpath ~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexshowpath [on | off] :Default: fancyindexshowpath on :Context: http, server, location :Description: Whether to output or not the path and the closing 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.

fancyindexshowdotfiles ~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexshowdotfiles [on | off] :Default: fancyindexshowdotfiles off :Context: http, server, location :Description: Whether to list files that are proceeded with a dot. Normal convention is to hide these.

fancyindexignore ~~~~~~~~~~~~~~~~~ :Syntax: *fancyindexignore string1 [string2 [... stringN]]* :Default: No default. :Context: http, server, location :Description: Specifies a list of file names which will be not be shown in generated listings. If Nginx was built with PCRE support strings are interpreted as regular expressions.

fancyindexhidesymlinks ~~~~~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindexhidesymlinks [on | off] :Default: fancyindexhidesymlinks off :Context: http, server, location :Description: When enabled, generated listings will not contain symbolic links.

fancyindexhideparentdir ~~~~~~~~~~~~~~~~~~~~~~~~ :Syntax: *fancyindexhideparentdir* [on | off] :Default: fancyindexhideparent_dir off :Context: http, server, location :Description: When enabled, it will not show parent directory.

fancyindexlocaltime ~~~~~~~~~~~~~~~~~~~~ :Syntax: *fancyindexlocaltime* [on | off] :Default: fancyindex_localtime off :Context: http, server, location :Description: Enables showing file times as local time. Default is “off” (GMT time).

fancyindextimeformat ~~~~~~~~~~~~~~~~~~~~~~ :Syntax: fancyindextimeformat string :Default: fancyindextimeformat "%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:
  • %a
    : Abbreviated name of the day of the week.
  • %A
    : Full name of the day of the week.
  • %b
    : Abbreviated month name.
  • %B
    : Full month name.
  • %d
    : Day of the month as a decimal number (range 01 to 31).
  • %e
    : Like
    %d
    , the day of the month as a decimal number, but a leading zero is replaced by a space.
  • %F
    : Equivalent to
    %Y-%m-%d
    (the ISO 8601 date format).
  • %H
    : Hour as a decimal number using a 24-hour clock (range 00 to 23).
  • %I
    : Hour as a decimal number using a 12-hour clock (range 01 to 12).
  • %k
    : Hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank.
  • %l
    : Hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank.
  • %m
    : Month as a decimal number (range 01 to 12).
  • %M
    : Minute as a decimal number (range 00 to 59).
  • %p
    : Either "AM" or "PM" according to the given time value.
  • %P
    : Like
    %p
    but in lowercase: "am" or "pm".
  • %r
    : Time in a.m. or p.m. notation. Equivalent to
    %I:%M:%S %p
    .
  • %R
    : Time in 24-hour notation (
    %H:%M
    ).
  • %S
    : Second as a decimal number (range 00 to 60).
  • %T
    : Time in 24-hour notation (
    %H:%M:%S
    ).
  • %u
    : Day of the week as a decimal, range 1 to 7, Monday being 1.
  • %w
    : Day of the week as a decimal, range 0 to 6, Monday being 0.
  • %y
    : Year as a decimal number without a century (range 00 to 99).
  • %Y
    : Year as a decimal number including the century.

.. _nginx: https://nginx.org

.. vim:ft=rst:spell:spelllang=en:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.