2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_autoindex.xml.meta">
24 <name>mod_autoindex</name>
26 <description>Generates directory indexes,
27 automatically, similar to the Unix <code>ls</code> command or the
28 Win32 <code>dir</code> shell command</description>
30 <sourcefile>mod_autoindex.c</sourcefile>
31 <identifier>autoindex_module</identifier>
34 <p>The index of a directory can come from one of two
38 <li>A file written by the user, typically called
39 <code>index.html</code>. The <directive
40 module="mod_dir">DirectoryIndex</directive> directive sets the
41 name of this file. This is controlled by
42 <module>mod_dir</module>.</li>
44 <li>Otherwise, a listing generated by the server. The other
45 directives control the format of this listing. The <directive
46 module="mod_autoindex">AddIcon</directive>, <directive
47 module="mod_autoindex">AddIconByEncoding</directive> and
48 <directive module="mod_autoindex">AddIconByType</directive> are
49 used to set a list of icons to display for various file types;
50 for each file listed, the first icon listed that matches the
51 file is displayed. These are controlled by
52 <module>mod_autoindex</module>.</li>
54 <p>The two functions are separated so that you can completely
55 remove (or replace) automatic index generation should you want
58 <p>Automatic index generation is enabled with using
59 <code>Options +Indexes</code>. See the
60 <directive module="core">Options</directive> directive for
63 <p>If the <code><a href="#indexoptions.fancyindexing"
64 >FancyIndexing</a></code> option is given with the <directive
65 module="mod_autoindex">IndexOptions</directive> directive,
66 the column headers are links that control the order of the
67 display. If you select a header link, the listing will be
68 regenerated, sorted by the values in that column. Selecting the
69 same header repeatedly toggles between ascending and descending
70 order. These column header links are suppressed with the
71 <directive module="mod_autoindex">IndexOptions</directive> directive's
72 <code>SuppressColumnSorting</code> option.</p>
74 <p>Note that when the display is sorted by "Size", it's the
75 <em>actual</em> size of the files that's used, not the
76 displayed value - so a 1010-byte file will always be displayed
77 before a 1011-byte file (if in ascending order) even though
78 they both are shown as "1K".</p>
82 <title>Autoindex Request Query Arguments</title>
84 <p>Apache HTTP Server 2.0.23 reorganized the Query Arguments for Column
85 Sorting, and introduced an entire group of new query options.
86 To effectively eliminate all client control over the output,
87 the <code><a href="#indexoptions.ignoreclient">IndexOptions
88 IgnoreClient</a></code> option was introduced.</p>
90 <p>The column sorting headers themselves are self-referencing
91 hyperlinks that add the sort query options shown below. Any
92 option below may be added to any request for the directory
96 <li><code>C=N</code> sorts the directory by file name</li>
98 <li><code>C=M</code> sorts the directory by last-modified
99 date, then file name</li>
101 <li><code>C=S</code> sorts the directory by size, then file
104 <li class="separate"><code>C=D</code> sorts the directory by description, then
107 <li><code>O=A</code> sorts the listing in Ascending
110 <li class="separate"><code>O=D</code> sorts the listing in Descending
113 <li><code>F=0</code> formats the listing as a simple list
114 (not FancyIndexed)</li>
116 <li><code>F=1</code> formats the listing as a FancyIndexed
119 <li class="separate"><code>F=2</code> formats the listing as an
120 HTMLTable FancyIndexed list</li>
122 <li><code>V=0</code> disables version sorting</li>
124 <li class="separate"><code>V=1</code> enables version sorting</li>
126 <li><code>P=<var>pattern</var></code> lists only files matching
127 the given <var>pattern</var></li>
130 <p>Note that the 'P'attern query argument is tested
131 <em>after</em> the usual <directive module="mod_autoindex"
132 >IndexIgnore</directive> directives are processed,
133 and all file names are still subjected to the same criteria as
134 any other autoindex listing. The Query Arguments parser in
135 <module>mod_autoindex</module> will stop abruptly when an unrecognized
136 option is encountered. The Query Arguments must be well formed,
137 according to the table above.</p>
139 <p>The simple example below, which can be clipped and saved in
140 a header.html file, illustrates these query options. Note that
141 the unknown "X" argument, for the submit button, is listed last
142 to assure the arguments are all parsed before mod_autoindex
143 encounters the X=Go input.</p>
146 <form action="" method="get"><br />
148 Show me a <select name="F"><br />
150 <option value="0"> Plain list</option><br />
151 <option value="1" selected="selected"> Fancy list</option><br />
152 <option value="2"> Table list</option><br />
154 </select><br />
155 Sorted by <select name="C"><br />
157 <option value="N" selected="selected"> Name</option><br />
158 <option value="M"> Date Modified</option><br />
159 <option value="S"> Size</option><br />
160 <option value="D"> Description</option><br />
162 </select><br />
163 <select name="O"><br />
165 <option value="A" selected="selected"> Ascending</option><br />
166 <option value="D"> Descending</option><br />
168 </select><br />
169 <select name="V"><br />
171 <option value="0" selected="selected"> in Normal order</option><br />
172 <option value="1"> in Version order</option><br />
174 </select><br />
175 Matching <input type="text" name="P" value="*" /><br />
176 <input type="submit" name="X" value="Go" /><br />
185 <description>Alternate text to display for a file, instead of an
186 icon selected by filename</description>
187 <syntax>AddAlt <var>string</var> <var>file</var> [<var>file</var>] ...</syntax>
188 <contextlist><context>server config</context><context>virtual host</context>
189 <context>directory</context><context>.htaccess</context>
191 <override>Indexes</override>
194 <p><directive>AddAlt</directive> provides the alternate text to
195 display for a file, instead of an icon, for <code><a
196 href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
197 <var>File</var> is a file extension, partial filename, wild-card
198 expression or full filename for files to describe.
199 If <var>String</var> contains any whitespace, you have to enclose it
200 in quotes (<code>"</code> or <code>'</code>). This alternate text
201 is displayed if the client is image-incapable, has image loading
202 disabled, or fails to retrieve the icon.</p>
204 <example><title>Examples</title>
205 AddAlt "PDF file" *.pdf<br />
206 AddAlt Compressed *.gz *.zip *.Z
212 <name>AddAltByEncoding</name>
213 <description>Alternate text to display for a file instead of an icon
214 selected by MIME-encoding</description>
215 <syntax>AddAltByEncoding <var>string</var> <var>MIME-encoding</var>
216 [<var>MIME-encoding</var>] ...</syntax>
217 <contextlist><context>server config</context><context>virtual host</context>
218 <context>directory</context><context>.htaccess</context>
220 <override>Indexes</override>
223 <p><directive>AddAltByEncoding</directive> provides the alternate
224 text to display for a file, instead of an icon, for <code><a
225 href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
226 <var>MIME-encoding</var> is a valid content-encoding, such as
227 <code>x-compress</code>. If <var>String</var> contains any whitespace,
228 you have to enclose it in quotes (<code>"</code> or <code>'</code>).
229 This alternate text is displayed if the client is image-incapable,
230 has image loading disabled, or fails to retrieve the icon.</p>
232 <example><title>Example</title>
233 AddAltByEncoding gzip x-gzip
239 <name>AddAltByType</name>
240 <description>Alternate text to display for a file, instead of an
241 icon selected by MIME content-type</description>
242 <syntax>AddAltByType <var>string</var> <var>MIME-type</var>
243 [<var>MIME-type</var>] ...</syntax>
244 <contextlist><context>server config</context><context>virtual host</context>
245 <context>directory</context><context>.htaccess</context>
247 <override>Indexes</override>
250 <p><directive>AddAltByType</directive> sets the alternate text to
251 display for a file, instead of an icon, for <code><a
252 href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
253 <var>MIME-type</var> is a valid content-type, such as
254 <code>text/html</code>. If <var>String</var> contains any whitespace,
255 you have to enclose it in quotes (<code>"</code> or <code>'</code>).
256 This alternate text is displayed if the client is image-incapable,
257 has image loading disabled, or fails to retrieve the icon.</p>
259 <example><title>Example</title>
260 AddAltByType 'plain text' text/plain
266 <name>AddDescription</name>
267 <description>Description to display for a file</description>
268 <syntax>AddDescription <var>string file</var> [<var>file</var>] ...</syntax>
269 <contextlist><context>server config</context><context>virtual host</context>
270 <context>directory</context><context>.htaccess</context>
272 <override>Indexes</override>
275 <p>This sets the description to display for a file, for
276 <code><a href="#indexoptions.fancyindexing"
277 >FancyIndexing</a></code>.
278 <var>File</var> is a file extension, partial filename, wild-card
279 expression or full filename for files to describe.
280 <var>String</var> is enclosed in double quotes (<code>"</code>).</p>
282 <example><title>Example</title>
283 AddDescription "The planet Mars" /web/pics/mars.gif
286 <p>The typical, default description field is 23 bytes wide. 6
287 more bytes are added by the <code><a href="#indexoptions.suppressicon"
288 >IndexOptions SuppressIcon</a></code> option, 7 bytes are
289 added by the <code><a href="#indexoptions.suppresssize"
290 >IndexOptions SuppressSize</a></code> option, and 19 bytes are
291 added by the <code><a href="#indexoptions.suppresslastmodified"
292 >IndexOptions SuppressLastModified</a></code> option.
293 Therefore, the widest default the description column is ever
294 assigned is 55 bytes.</p>
296 <p>Since the <var>File</var> argument may be a partial file name,
297 please remember that a too-short partial filename may match
298 unintended files. For example, <code>le.html</code> will match the
299 file <code>le.html</code> but will also match the file
300 <code>example.html</code>. In the event that there may be ambiguity,
301 use as complete a filename as you can, but keep in mind that the
302 first match encountered will be used, and order your list of
303 <code>AddDescription</code> directives accordingly.</p>
305 <p>See the <a href="#indexoptions.descriptionwidth"
306 >DescriptionWidth</a> <directive module="mod_autoindex"
307 >IndexOptions</directive> keyword for details on overriding the size
308 of this column, or allowing descriptions of unlimited length.</p>
310 <note><title>Caution</title>
311 <p>Descriptive text defined with <directive>AddDescription</directive>
312 may contain HTML markup, such as tags and character entities. If the
313 width of the description column should happen to truncate a tagged
314 element (such as cutting off the end of a bolded phrase), the
315 results may affect the rest of the directory listing.</p>
322 <description>Icon to display for a file selected by name</description>
323 <syntax>AddIcon <var>icon</var> <var>name</var> [<var>name</var>]
325 <contextlist><context>server config</context><context>virtual host</context>
326 <context>directory</context><context>.htaccess</context>
328 <override>Indexes</override>
331 <p>This sets the icon to display next to a file ending in
332 <var>name</var> for <code><a href="#indexoptions.fancyindexing"
333 >FancyIndexing</a></code>. <var>Icon</var> is either a (%-escaped)
334 relative URL to the icon, or of the format <code>
335 (<var>alttext</var>,<var>url</var>)</code> where <var>alttext</var>
336 is the text tag given for an icon for non-graphical browsers.</p>
338 <p><var>Name</var> is either <code>^^DIRECTORY^^</code> for directories,
339 <code>^^BLANKICON^^</code> for blank lines (to format the list
340 correctly), a file extension, a wildcard expression, a partial
341 filename or a complete filename.</p>
343 <example><title>Examples</title>
344 AddIcon (IMG,/icons/image.png) .gif .jpg .png<br />
345 AddIcon /icons/dir.png ^^DIRECTORY^^<br />
346 AddIcon /icons/backup.png *~
349 <p><directive module="mod_autoindex">AddIconByType</directive>
350 should be used in preference to <directive>AddIcon</directive>,
356 <name>AddIconByEncoding</name>
357 <description>Icon to display next to files selected by MIME
358 content-encoding</description>
359 <syntax>AddIconByEncoding <var>icon</var> <var>MIME-encoding</var>
360 [<var>MIME-encoding</var>] ...</syntax>
361 <contextlist><context>server config</context><context>virtual host</context>
362 <context>directory</context><context>.htaccess</context>
364 <override>Indexes</override>
367 <p>This sets the icon to display next to files with <code><a
368 href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
369 <var>Icon</var> is either a (%-escaped) relative URL to the icon,
370 or of the format <code>(<var>alttext</var>,<var>url</var>)</code>
371 where <var>alttext</var> is the text tag given for an icon for
372 non-graphical browsers.</p>
374 <p><var>MIME-encoding</var> is a valid content-encoding, such as
375 <code>x-compress</code>.</p>
377 <example><title>Example</title>
378 AddIconByEncoding /icons/compress.png x-compress
384 <name>AddIconByType</name>
385 <description>Icon to display next to files selected by MIME
386 content-type</description>
387 <syntax>AddIconByType <var>icon</var> <var>MIME-type</var>
388 [<var>MIME-type</var>] ...</syntax>
389 <contextlist><context>server config</context><context>virtual host</context>
390 <context>directory</context><context>.htaccess</context>
392 <override>Indexes</override>
395 <p>This sets the icon to display next to files of type
396 <var>MIME-type</var> for <code><a
397 href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
398 <var>Icon</var> is either a (%-escaped) relative URL to the icon,
399 or of the format <code>(<var>alttext</var>,<var>url</var>)</code>
400 where <var>alttext</var> is the text tag given for an icon for
401 non-graphical browsers.</p>
403 <p><var>MIME-type</var> is a wildcard expression matching
404 required the mime types.</p>
406 <example><title>Example</title>
407 AddIconByType (IMG,/icons/image.png) image/*
413 <name>DefaultIcon</name>
414 <description>Icon to display for files when no specific icon is
415 configured</description>
416 <syntax>DefaultIcon <var>url-path</var></syntax>
417 <contextlist><context>server config</context><context>virtual host</context>
418 <context>directory</context><context>.htaccess</context>
420 <override>Indexes</override>
423 <p>The <directive>DefaultIcon</directive> directive sets the icon
424 to display for files when no specific icon is known, for <code><a
425 href="#indexoptions.fancyindexing">FancyIndexing</a></code>.
426 <var>Url-path</var> is a (%-escaped) relative URL to the icon.</p>
428 <example><title>Example</title>
429 DefaultIcon /icon/unknown.png
435 <name>HeaderName</name>
436 <description>Name of the file that will be inserted at the top
437 of the index listing</description>
438 <syntax>HeaderName <var>filename</var></syntax>
439 <contextlist><context>server config</context><context>virtual host</context>
440 <context>directory</context><context>.htaccess</context>
442 <override>Indexes</override>
445 <p>The <directive>HeaderName</directive> directive sets the name
446 of the file that will be inserted at the top of the index
447 listing. <var>Filename</var> is the name of the file to include.</p>
449 <example><title>Example</title>
450 HeaderName HEADER.html
454 <p>Both HeaderName and <directive
455 module="mod_autoindex">ReadmeName</directive> now treat
456 <var>Filename</var> as a URI path relative to the one used to
457 access the directory being indexed. If <var>Filename</var> begins
458 with a slash, it will be taken to be relative to the <directive
459 module="core">DocumentRoot</directive>.</p>
461 <example><title>Example</title>
462 HeaderName /include/HEADER.html
465 <p><var>Filename</var> must resolve to a document with a major
466 content type of <code>text/*</code> (<em>e.g.</em>,
467 <code>text/html</code>, <code>text/plain</code>, etc.). This means
468 that <var>filename</var> may refer to a CGI script if the script's
469 actual file type (as opposed to its output) is marked as
470 <code>text/html</code> such as with a directive like:</p>
473 AddType text/html .cgi
476 <p><a href="../content-negotiation.html">Content negotiation</a>
477 will be performed if <directive module="core">Options</directive>
478 <code>MultiViews</code> is in effect. If <var>filename</var> resolves
479 to a static <code>text/html</code> document (not a CGI script) and
480 either one of the <directive module="core">options</directive>
481 <code>Includes</code> or <code>IncludesNOEXEC</code> is enabled,
482 the file will be processed for server-side includes (see the
483 <module>mod_include</module> documentation).</p>
486 <p>If the file specified by <directive>HeaderName</directive> contains
487 the beginnings of an HTML document (<html>, <head>, etc.)
488 then you will probably want to set <a
489 href="#indexoptions.suppresshtmlpreamble"><code>IndexOptions
490 +SuppressHTMLPreamble</code></a>, so that these tags are not
496 <name>IndexIgnore</name>
497 <description>Adds to the list of files to hide when listing
498 a directory</description>
499 <syntax>IndexIgnore <var>file</var> [<var>file</var>] ...</syntax>
500 <contextlist><context>server config</context><context>virtual host</context>
501 <context>directory</context><context>.htaccess</context>
503 <override>Indexes</override>
506 <p>The <directive>IndexIgnore</directive> directive adds to the
507 list of files to hide when listing a directory. <var>File</var> is a
508 shell-style wildcard expression or full
509 filename. Multiple IndexIgnore directives add
510 to the list, rather than the replacing the list of ignored
511 files. By default, the list contains <code>.</code> (the current
515 IndexIgnore README .htaccess *.bak *~
521 <name>IndexOptions</name>
522 <description>Various configuration settings for directory
523 indexing</description>
524 <syntax>IndexOptions [+|-]<var>option</var> [[+|-]<var>option</var>]
526 <contextlist><context>server config</context><context>virtual host</context>
527 <context>directory</context><context>.htaccess</context>
529 <override>Indexes</override>
532 <p>The <directive>IndexOptions</directive> directive specifies the
533 behavior of the directory indexing. <var>Option</var> can be one
537 <dt><a name="indexoptions.addaltclass"
538 id="indexoptions.addaltclass">AddAltClass</a></dt>
539 <dd>Adds an additional CSS class declaration to each row of the
540 directory listing table when <code>IndexOptions HTMLTable</code>
541 is in effect and an <code>IndexStyleSheet</code> is defined.
542 Rather than the standard <code>even</code> and <code>odd</code>
543 classes that would otherwise be applied to each row of the table,
544 a class of <code>even-<em>ALT</em></code> or
545 <code>odd-<em>ALT</em></code> where <em>ALT</em> is either the
546 standard alt text associated with the file style (eg. <em>snd</em>,
547 <em>txt</em>, <em>img</em>, etc) or the alt text defined by one of
548 the various <code>AddAlt*</code> directives.
551 <dt><a name="indexoptions.charset"
552 id="indexoptions.charset"
553 >Charset=<var>character-set</var></a> (<em>Apache HTTP Server 2.0.61 and
556 <dd>The <code>Charset</code> keyword allows you to
557 specify the character set of the generated page. The
558 default is either <var>ISO-8859-1</var> or <var>UTF-8</var>,
559 depending on whether the underlying file system is unicode
562 <example><title>Example:</title>
563 IndexOptions Charset=UTF-8
567 <dt><a name="indexoptions.descriptionwidth"
568 id="indexoptions.descriptionwidth"
569 >DescriptionWidth=[<var>n</var> | *]</a> (<em>Apache HTTP Server 2.0.23 and
572 <dd>The <code>DescriptionWidth</code> keyword allows you to
573 specify the width of the description column in
576 <dd><code>-DescriptionWidth</code> (or unset) allows
577 <module>mod_autoindex</module> to calculate the best width.</dd>
579 <dd><code>DescriptionWidth=<var>n</var></code> fixes the column width to
580 <var>n</var> bytes wide.</dd>
582 <dd><code>DescriptionWidth=*</code> grows the column to the
583 width necessary to accommodate the longest description
586 <dd><strong>See the section on <directive
587 module="mod_autoindex">AddDescription</directive> for dangers
588 inherent in truncating descriptions.</strong></dd>
590 <dt><a name="indexoptions.fancyindexing"
591 id="indexoptions.fancyindexing">FancyIndexing</a></dt>
593 <dd>This turns on fancy indexing of directories.</dd>
595 <dt><a name="indexoptions.foldersfirst"
596 id="indexoptions.foldersfirst">FoldersFirst</a> (<em>Apache HTTP Server
597 2.0.23 and later</em>)</dt>
599 <dd>If this option is enabled, subdirectory listings will
600 <em>always</em> appear first, followed by normal files in the
601 directory. The listing is basically broken into two
602 components, the files and the subdirectories, and each is
603 sorted separately and then displayed subdirectories-first.
604 For instance, if the sort order is descending by name, and
605 <code>FoldersFirst</code> is enabled, subdirectory
606 <code>Zed</code> will be listed before subdirectory
607 <code>Beta</code>, which will be listed before normal files
608 <code>Gamma</code> and <code>Alpha</code>. <strong>This option
609 only has an effect if <a href="#indexoptions.fancyindexing"
610 ><code>FancyIndexing</code></a> is also enabled.</strong></dd>
612 <dt><a name="indexoptions.htmltable"
613 id="indexoptions.htmltable">HTMLTable</a> (<em>Apache
614 HTTP Server 2.0.23 and later</em>)</dt>
616 <dd>This option with <code>FancyIndexing</code> constructs
617 a simple table for the fancy directory listing.
618 It is necessary for utf-8 enabled platforms or if file
619 names or description text will alternate between
620 left-to-right and right-to-left reading order.</dd>
622 <dt><a name="indexoptions.iconsarelinks"
623 id="indexoptions.iconsarelinks">IconsAreLinks</a></dt>
625 <dd>This makes the icons part of the anchor for the filename, for
628 <dt><a name="indexoptions.iconheight"
629 id="indexoptions.iconheight">IconHeight[=<var
630 >pixels</var>]</a></dt>
632 <dd>Presence of this option, when used with <code>IconWidth</code>,
633 will cause the server to include <code>height</code> and
634 <code>width</code> attributes in the <code>img</code> tag for the file
635 icon. This allows browser to precalculate the page layout without having
636 to wait until all the images have been loaded. If no value is given for
637 the option, it defaults to the standard height of the icons supplied
638 with the Apache httpd software.</dd>
640 <dt><a name="indexoptions.iconwidth"
641 id="indexoptions.iconwidth">IconWidth[=<var
642 >pixels</var>]</a></dt>
644 <dd>Presence of this option, when used with <code>IconHeight</code>,
645 will cause the server to include <code>height</code> and
646 <code>width</code> attributes in the <code>img</code> tag for
647 the file icon. This allows browser to precalculate the page
648 layout without having to wait until all the images have been
649 loaded. If no value is given for the option, it defaults to
650 the standard width of the icons supplied with the Apache httpd
653 <dt><a name="indexoptions.ignorecase"
654 id="indexoptions.ignorecase">IgnoreCase</a></dt>
656 <dd>If this option is enabled, names are sorted in a case-insensitive
657 manner. For instance, if the sort order is ascending by name, and
658 <code>IgnoreCase</code> is enabled, file Zeta will be listed after
659 file alfa (Note: file GAMMA will always be listed before file gamma).
662 <dt><a name="indexoptions.ignoreclient"
663 id="indexoptions.ignoreclient">IgnoreClient</a></dt>
665 <dd>This option causes <module>mod_autoindex</module> to ignore all
666 query variables from the client, including sort order (implies
667 <code><a href="#indexoptions.suppresscolumnsorting"
668 >SuppressColumnSorting</a></code>.)</dd>
670 <dt><a name="indexoptions.namewidth"
671 id="indexoptions.namewidth">NameWidth=[<var>n</var>
674 <dd>The <code>NameWidth</code> keyword allows you to specify the width
675 of the filename column in bytes.</dd>
677 <dd><code>-NameWidth</code> (or unset) allows <module
678 >mod_autoindex</module> to calculate the best width, but only up
679 to 20 bytes wide.</dd>
681 <dd><code>NameWidth=<var>n</var></code> fixes the column width to
682 <var>n</var> bytes wide.</dd>
684 <dd><code>NameWidth=*</code> grows the column to the necessary
687 <dt><a name="indexoptions.scanhtmltitles"
688 id="indexoptions.scanhtmltitles">ScanHTMLTitles</a></dt>
690 <dd>This enables the extraction of the title from HTML documents
691 for fancy indexing. If the file does not have a description
692 given by <directive module="mod_autoindex">AddDescription</directive>
693 then httpd will read the document for the value of the
694 <code>title</code> element. This is CPU and disk intensive.</dd>
696 <dt><a name="indexoptions.showforbidden"
697 id="indexoptions.showforbidden">ShowForbidden</a></dt>
699 <dd>If specified, Apache httpd will show files normally hidden because
700 the subrequest returned <code>HTTP_UNAUTHORIZED</code> or
701 <code>HTTP_FORBIDDEN</code></dd>
703 <dt><a name="indexoptions.suppresscolumnsorting"
704 id="indexoptions.suppresscolumnsorting"
705 >SuppressColumnSorting</a></dt>
707 <dd>If specified, Apache httpd will not make the column headings in a
708 FancyIndexed directory listing into links for sorting. The
709 default behavior is for them to be links; selecting the
710 column heading will sort the directory listing by the values
711 in that column. <strong>Prior to Apache HTTP Server 2.0.23, this also
712 disabled parsing the Query Arguments for the sort
713 string.</strong> That behavior is now controlled by <a
714 href="#indexoptions.ignoreclient"><code>IndexOptions
715 IgnoreClient</code></a> in Apache HTTP Server 2.0.23.</dd>
717 <dt><a name="indexoptions.suppressdescription"
718 id="indexoptions.suppressdescription"
719 >SuppressDescription</a></dt>
721 <dd>This will suppress the file description in fancy indexing
722 listings. By default, no file descriptions are defined, and
723 so the use of this option will regain 23 characters of screen
724 space to use for something else. See <directive module="mod_autoindex"
725 >AddDescription</directive> for information about setting the file
726 description. See also the <code><a
727 href="#indexoptions.descriptionwidth">DescriptionWidth</a></code>
728 index option to limit the size of the description column.</dd>
730 <dt><a name="indexoptions.suppresshtmlpreamble"
731 id="indexoptions.suppresshtmlpreamble"
732 >SuppressHTMLPreamble</a></dt>
734 <dd>If the directory actually contains a file specified by the
735 <directive module="mod_autoindex">HeaderName</directive>
736 directive, the module usually includes the contents of the file
737 after a standard HTML preamble (<code><html></code>,
738 <code><head></code>, <em>et cetera</em>). The
739 <code>SuppressHTMLPreamble</code> option disables this behaviour,
740 causing the module to start the display with the header file
741 contents. The header file must contain appropriate HTML instructions
742 in this case. If there is no header file, the preamble is generated
743 as usual. If you also specify a <directive
744 module="mod_autoindex">ReadmeName</directive>, and if that file
745 exists, The closing </body></html> tags are also
746 ommitted from the output, under the assumption that you'll likely
747 put those closing tags in that file.</dd>
749 <dt><a name="indexoptions.suppressicon"
750 id="indexoptions.suppressicon">SuppressIcon</a> (<em>Apache HTTP Server
751 2.0.23 and later</em>)</dt>
753 <dd>This will suppress the icon in fancy indexing listings.
754 Combining both <code>SuppressIcon</code> and
755 <code>SuppressRules</code> yields proper HTML 3.2 output, which
756 by the final specification prohibits <code>img</code> and
757 <code>hr</code> elements from the <code>pre</code> block (used to
758 format FancyIndexed listings.)</dd>
760 <dt><a name="indexoptions.suppresslastmodified"
761 id="indexoptions.suppresslastmodified"
762 >SuppressLastModified</a></dt>
764 <dd>This will suppress the display of the last modification date,
765 in fancy indexing listings.</dd>
767 <dt><a name="indexoptions.suppressrules"
768 id="indexoptions.suppressrules">SuppressRules</a>
769 (<em>Apache HTTP Server 2.0.23 and later</em>)</dt>
771 <dd>This will suppress the horizontal rule lines (<code>hr</code>
772 elements) in directory listings. Combining both <code>SuppressIcon</code> and
773 <code>SuppressRules</code> yields proper HTML 3.2 output, which
774 by the final specification prohibits <code>img</code> and
775 <code>hr</code> elements from the <code>pre</code> block (used to
776 format FancyIndexed listings.)</dd>
778 <dt><a name="indexoptions.suppresssize"
779 id="indexoptions.suppresssize">SuppressSize</a></dt>
781 <dd>This will suppress the file size in fancy indexing listings.</dd>
783 <dt><a name="indexoptions.trackmodified"
784 id="indexoptions.trackmodified">TrackModified</a> (<em>Apache HTTP Server
785 2.0.23 and later</em>)</dt>
787 <dd>This returns the <code>Last-Modified</code> and <code>ETag</code>
788 values for the listed directory in the HTTP header. It is only valid
789 if the operating system and file system return appropriate stat()
790 results. Some Unix systems do so, as do OS2's JFS and Win32's
791 NTFS volumes. OS2 and Win32 FAT volumes, for example, do not.
792 Once this feature is enabled, the client or proxy can track
793 changes to the list of files when they perform a <code>HEAD</code>
794 request. Note some operating systems correctly track new and
795 removed files, but do not track changes for sizes or dates of
796 the files within the directory. <strong>Changes to the size
797 or date stamp of an existing file will not update the
798 <code>Last-Modified</code> header on all Unix platforms.</strong>
799 If this is a concern, leave this option disabled.</dd>
801 <dt><a name="indexoptions.type"
802 id="indexoptions.type"
803 >Type=<var>MIME content-type</var></a> (<em>Apache HTTP Server 2.0.61 and
806 <dd>The <code>Type</code> keyword allows you to
807 specify the MIME content-type of the generated page. The default
808 is <var>text/html</var>.
810 <example><title>Example:</title>
811 IndexOptions Type=text/plain
815 <dt><a name="indexoptions.versionsort"
816 id="indexoptions.versionsort">VersionSort</a>
817 (<em>Apache HTTP Server 2.0a3 and later</em>)</dt>
819 <dd>The <code>VersionSort</code> keyword causes files containing
820 version numbers to sort in a natural way. Strings are sorted as
821 usual, except that substrings of digits in the name and
822 description are compared according to their numeric value.
824 <example><title>Example:</title>
833 <p>If the number starts with a zero, then it is considered to
844 <dt><a name="indexoptions.xhtml"
845 id="indexoptions.xhtml">XHTML</a>
846 (<em>Apache HTTP Server 2.0.49 and later</em>)</dt>
848 <dd>The <code>XHTML</code> keyword forces <module>mod_autoindex</module>
849 to emit XHTML 1.0 code instead of HTML 3.2.</dd>
854 XXX: we should consider to allow sections inside <usage>
855 this would require some xslt changes...
857 <dl><dt>Incremental IndexOptions</dt>
859 <p>Be aware of how multiple <directive>IndexOptions</directive> are
863 <li>Multiple <directive>IndexOptions</directive> directives for a
864 single directory are now merged together. The result of:
867 <Directory /foo>
869 IndexOptions HTMLTable<br />
870 IndexOptions SuppressColumnsorting
875 <p>will be the equivalent of</p>
878 IndexOptions HTMLTable SuppressColumnsorting
882 <li>The addition of the incremental syntax (<em>i.e.</em>, prefixing
883 keywords with <code>+</code> or <code>-</code>).</li>
886 <p>Whenever a '+' or '-' prefixed keyword is encountered, it
887 is applied to the current <directive>IndexOptions</directive>
888 settings (which may have been inherited from an upper-level
889 directory). However, whenever an unprefixed keyword is processed, it
890 clears all inherited options and any incremental settings encountered
891 so far. Consider the following example:</p>
894 IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing<br />
895 IndexOptions +SuppressSize
898 <p>The net effect is equivalent to <code>IndexOptions FancyIndexing
899 +SuppressSize</code>, because the unprefixed <code>FancyIndexing</code>
900 discarded the incremental keywords before it, but allowed them to
901 start accumulating again afterward.</p>
903 <p>To unconditionally set the <directive>IndexOptions</directive> for
904 a particular directory, clearing the inherited settings, specify
905 keywords without any <code>+</code> or <code>-</code> prefixes.</p>
912 <name>IndexOrderDefault</name>
913 <description>Sets the default ordering of the directory index</description>
914 <syntax>IndexOrderDefault Ascending|Descending
915 Name|Date|Size|Description</syntax>
916 <default>IndexOrderDefault Ascending Name</default>
917 <contextlist><context>server config</context><context>virtual host</context>
918 <context>directory</context><context>.htaccess</context>
920 <override>Indexes</override>
923 <p>The <directive>IndexOrderDefault</directive> directive is used
924 in combination with the <code><a href="#indexoptions.fancyindexing"
925 >FancyIndexing</a></code> index option. By default, fancyindexed
926 directory listings are displayed in ascending order by filename; the
927 <directive>IndexOrderDefault</directive> allows you to change this
928 initial display order.</p>
930 <p><directive>IndexOrderDefault</directive> takes two
931 arguments. The first must be either <code>Ascending</code> or
932 <code>Descending</code>, indicating the direction of the sort.
933 The second argument must be one of the keywords <code>Name</code>,
934 <code>Date</code>, <code>Size</code>, or <code>Description</code>,
935 and identifies the primary key. The secondary key is
936 <em>always</em> the ascending filename.</p>
938 <p>You can force a directory listing to only be displayed in a
939 particular order by combining this directive with the <code><a
940 href="#indexoptions.suppresscolumnsorting"
941 >SuppressColumnSorting</a></code> index option; this will prevent
942 the client from requesting the directory listing in a different
948 <name>IndexStyleSheet</name>
949 <description>Adds a CSS stylesheet to the directory index</description>
950 <syntax>IndexStyleSheet <var>url-path</var></syntax>
951 <contextlist><context>server config</context><context>virtual host</context>
952 <context>directory</context><context>.htaccess</context>
954 <override>Indexes</override>
957 <p>The <directive>IndexStyleSheet</directive> directive sets the name of
958 the file that will be used as the CSS for the index listing.
961 <title>Example</title>
962 IndexStyleSheet "/css/style.css"
965 <p>Using this directive in conjunction with <code>IndexOptions
966 HTMLTable</code> adds a number of CSS classes to the resulting HTML.
967 The entire table is given a CSS id of <code>indexlist</code> and the
968 following classes are associated with the various parts of the
972 <tr><th>Class</th><th>Definition</th></tr>
973 <tr><td>tr.indexhead</td><td>Header row of listing</td></tr>
974 <tr><td>th.indexcolicon and td.indexcolicon</td> <td>Icon column</td></tr>
975 <tr><td>th.indexcolname and td.indexcolname</td> <td>File name column</td></tr>
976 <tr><td>th.indexcollastmod and td.indexcollastmod</td> <td>Last modified column</td></tr>
977 <tr><td>th.indexcolsize and td.indexcolsize</td> <td>File size column</td></tr>
978 <tr><td>th.indexcoldesc and td.indexcoldesc</td> <td>Description column</td></tr>
979 <tr><td>tr.breakrow</td> <td>Horizontal rule at the bottom of the table</td></tr>
980 <tr><td>tr.odd and tr.even</td> <td>Alternating even and odd rows</td></tr>
987 <name>IndexHeadInsert</name>
988 <description>Inserts text in the HEAD section of an index page.</description>
989 <syntax>IndexHeadInsert <var>"markup ..."</var></syntax>
990 <contextlist><context>server config</context><context>virtual host</context>
991 <context>directory</context><context>.htaccess</context>
993 <override>Indexes</override>
996 <p>The <directive>IndexHeadInsert</directive> directive specifies a
997 string to insert in the <var><head></var> section of the HTML
998 generated for the index page.</p>
1000 <title>Example</title>
1001 IndexHeadInsert "<link rel=\"sitemap\" href=\"/sitemap.html\">"
1004 </directivesynopsis>
1007 <name>ReadmeName</name>
1008 <description>Name of the file that will be inserted at the end
1009 of the index listing</description>
1010 <syntax>ReadmeName <var>filename</var></syntax>
1011 <contextlist><context>server config</context><context>virtual host</context>
1012 <context>directory</context><context>.htaccess</context>
1014 <override>Indexes</override>
1017 <p>The <directive>ReadmeName</directive> directive sets the name
1018 of the file that will be appended to the end of the index
1019 listing. <var>Filename</var> is the name of the file to include, and
1020 is taken to be relative to the location being indexed. If
1021 <var>Filename</var> begins with a slash, it will be taken to be
1022 relative to the <directive module="core">DocumentRoot</directive>.
1025 <example><title>Example</title>
1026 ReadmeName FOOTER.html
1029 <example><title>Example 2</title>
1030 ReadmeName /include/FOOTER.html
1033 <p>See also <directive module="mod_autoindex"
1034 >HeaderName</directive>, where this behavior is described in greater
1037 </directivesynopsis>