1.7.3

closes #20
closes #30

.travis.yml

@@ -2,10 +2,19 @@ language: node_js
 node_js:
   - "0.8"
   - "0.10"
-  - "0.11"
-matrix:
-  allow_failures:
-    - node_js: "0.11"
-  fast_finish: true
-script: "npm run-script test-travis"
-after_script: "npm install coveralls@2.10.0 && cat ./coverage/lcov.info | coveralls"
+  - "0.12"
+  - "1.8"
+  - "2.5"
+  - "3.3"
+  - "4.2"
+  - "5.3"
+sudo: false
+before_install:
+  # Setup Node.js version-specific dependencies
+  - "test $TRAVIS_NODE_VERSION != '0.8' || npm rm --save-dev istanbul"
+script:
+  # Run test script, depending on istanbul install
+  - "test ! -z $(npm -ps ls istanbul) || npm test"
+  - "test   -z $(npm -ps ls istanbul) || npm run-script test-ci"
+after_script:
+  - "test -e ./coverage/lcov.info && npm install coveralls@2 && cat ./coverage/lcov.info | coveralls"

HISTORY.md

@@ -1,3 +1,118 @@
+1.7.3 / 2016-01-24
+==================
+
+  * deps: accepts@~1.2.13
+    - deps: mime-types@~2.1.6
+  * deps: batch@0.5.3
+    - Fix invalid dependency for browserify
+  * deps: escape-html@~1.0.3
+    - perf: enable strict mode
+    - perf: optimize string replacement
+    - perf: use faster string coercion
+  * deps: mime-types@~2.1.9
+    - Add new mime types
+  * deps: parseurl@~1.3.1
+    - perf: enable strict mode
+
+1.7.2 / 2015-07-30
+==================
+
+  * deps: accepts@~1.2.12
+    - deps: mime-types@~2.1.4
+  * deps: mime-types@~2.1.4
+    - Add new mime types
+
+1.7.1 / 2015-07-05
+==================
+
+  * deps: accepts@~1.2.10
+    - deps: mime-types@~2.1.2
+  * deps: mime-types@~2.1.2
+    - Add new mime types
+
+1.7.0 / 2015-06-15
+==================
+
+  * Accept `function` value for `template` option
+  * Send non-chunked response for `OPTIONS`
+  * Stat parent directory when necessary
+  * Use `Date.prototype.toLocaleDateString` to format date
+  * deps: accepts@~1.2.9
+    - deps: mime-types@~2.1.1
+    - deps: negotiator@0.5.3
+    - perf: avoid argument reassignment & argument slice
+    - perf: avoid negotiator recursive construction
+    - perf: enable strict mode
+    - perf: remove unnecessary bitwise operator
+  * deps: escape-html@1.0.2
+  * deps: mime-types@~2.1.1
+    - Add new mime types
+  * perf: enable strict mode
+  * perf: remove argument reassignment
+
+1.6.4 / 2015-05-12
+==================
+
+  * deps: accepts@~1.2.7
+    - deps: mime-types@~2.0.11
+    - deps: negotiator@0.5.3
+  * deps: debug@~2.2.0
+    - deps: ms@0.7.1
+  * deps: mime-types@~2.0.11
+    - Add new mime types
+
+1.6.3 / 2015-03-13
+==================
+
+  * Properly escape file names in HTML
+  * deps: accepts@~1.2.5
+    - deps: mime-types@~2.0.10
+  * deps: debug@~2.1.3
+    - Fix high intensity foreground color for bold
+    - deps: ms@0.7.0
+  * deps: escape-html@1.0.1
+  * deps: mime-types@~2.0.10
+    - Add new mime types
+
+1.6.2 / 2015-02-16
+==================
+
+  * deps: accepts@~1.2.4
+    - deps: mime-types@~2.0.9
+    - deps: negotiator@0.5.1
+  * deps: http-errors@~1.3.1
+    - Construct errors using defined constructors from `createError`
+    - Fix error names that are not identifiers
+    - Set a meaningful `name` property on constructed errors
+  * deps: mime-types@~2.0.9
+    - Add new mime types
+    - deps: mime-db@~1.7.0
+
+1.6.1 / 2015-01-31
+==================
+
+  * deps: accepts@~1.2.3
+    - deps: mime-types@~2.0.8
+  * deps: mime-types@~2.0.8
+    - Add new mime types
+    - deps: mime-db@~1.6.0
+
+1.6.0 / 2015-01-01
+==================
+
+  * Add link to root directory
+  * deps: accepts@~1.2.2
+    - deps: mime-types@~2.0.7
+    - deps: negotiator@0.5.0
+  * deps: batch@0.5.2
+  * deps: debug@~2.1.1
+  * deps: mime-types@~2.0.7
+    - Add new mime types
+    - Fix missing extensions
+    - Fix various invalid MIME type entries
+    - Remove example template MIME types
+    - deps: mime-db@~1.5.0
+
 1.5.3 / 2014-12-10
 ==================
 

LICENSE

@@ -3,7 +3,7 @@
 Copyright (c) 2010 Sencha Inc.
 Copyright (c) 2011 LearnBoost
 Copyright (c) 2011 TJ Holowaychuk
-Copyright (c) 2014 Douglas Christopher Wilson
+Copyright (c) 2014-2015 Douglas Christopher Wilson
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -2,7 +2,8 @@
 
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
-[![Build Status][travis-image]][travis-url]
+[![Linux Build][travis-image]][travis-url]
+[![Windows Build][appveyor-image]][appveyor-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
 [![Gratipay][gratipay-image]][gratipay-url]
 
@@ -55,15 +56,31 @@ Optional path to a CSS stylesheet. Defaults to a built-in stylesheet.
 
 ##### template
 
-Optional path to an HTML template. Defaults to a built-in template.
+Optional path to an HTML template or a function that will render a HTML
+string. Defaults to a built-in template.
 
-The following tokens are replaced in templates:
+When given a string, the string is used as a file path to load and then the
+following tokens are replaced in templates:
 
   * `{directory}` with the name of the directory.
   * `{files}` with the HTML of an unordered list of file links.
   * `{linked-path}` with the HTML of a link to the directory.
   * `{style}` with the specified stylesheet and embedded images.
 
+When given as a function, the function is called as `template(locals, callback)`
+and it needs to invoke `callback(error, htmlString)`. The following are the
+provided locals:
+
+  * `directory` is the directory being displayed (where `/` is the root).
+  * `displayIcons` is a Boolean for if icons should be rendered or not.
+  * `fileList` is a sorted array of files in the directory. The array contains
+    objects with the following properties:
+    - `name` is the relative name for the file.
+    - `stat` is a `fs.Stats` object for the file.
+  * `path` is the full filesystem path to `directory`.
+  * `style` is the default stylesheet or the contents of the `stylesheet` option.
+  * `viewName` is the view name provided by the `view` option.
+
 ##### view
 
 Display mode. `tiles` and `details` are available. Defaults to `tiles`.
@@ -115,13 +132,15 @@ app.listen()
 [MIT](LICENSE). The [Silk](http://www.famfamfam.com/lab/icons/silk/) icons
 are created by/copyright of [FAMFAMFAM](http://www.famfamfam.com/).
 
-[npm-image]: https://img.shields.io/npm/v/serve-index.svg?style=flat
+[npm-image]: https://img.shields.io/npm/v/serve-index.svg
 [npm-url]: https://npmjs.org/package/serve-index
-[travis-image]: https://img.shields.io/travis/expressjs/serve-index.svg?style=flat
+[travis-image]: https://img.shields.io/travis/expressjs/serve-index/master.svg?label=linux
 [travis-url]: https://travis-ci.org/expressjs/serve-index
-[coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-index.svg?style=flat
+[appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-index/master.svg?label=windows
+[appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-index
+[coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-index/master.svg
 [coveralls-url]: https://coveralls.io/r/expressjs/serve-index?branch=master
-[downloads-image]: https://img.shields.io/npm/dm/serve-index.svg?style=flat
+[downloads-image]: https://img.shields.io/npm/dm/serve-index.svg
 [downloads-url]: https://npmjs.org/package/serve-index
-[gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg?style=flat
+[gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
 [gratipay-url]: https://www.gratipay.com/dougwilson/

appveyor.yml

@@ -0,0 +1,22 @@
+environment:
+  matrix:
+    - nodejs_version: "0.8"
+    - nodejs_version: "0.10"
+    - nodejs_version: "0.12"
+    - nodejs_version: "1.8"
+    - nodejs_version: "2.5"
+    - nodejs_version: "3.3"
+    - nodejs_version: "4.2"
+    - nodejs_version: "5.3"
+install:
+  - ps: Install-Product node $env:nodejs_version
+  - if "%nodejs_version%" equ "0.8" npm rm --save-dev istanbul
+  - npm install
+build: off
+test_script:
+  - node --version
+  - npm --version
+  - set npm_test_command=test
+  - for /f %%l in ('npm -ps ls istanbul') do set npm_test_command=test-ci
+  - npm run %npm_test_command%
+version: "{build}"

index.js

@@ -2,20 +2,21 @@
  * serve-index
  * Copyright(c) 2011 Sencha Inc.
  * Copyright(c) 2011 TJ Holowaychuk
- * Copyright(c) 2014 Douglas Christopher Wilson
+ * Copyright(c) 2014-2015 Douglas Christopher Wilson
  * MIT Licensed
  */
 
-// TODO: arrow key navigation
-// TODO: make icons extensible
+'use strict';
 
 /**
  * Module dependencies.
+ * @private
  */
 
 var accepts = require('accepts');
 var createError = require('http-errors');
 var debug = require('debug')('serve-index');
+var escapeHtml = require('escape-html');
 var fs = require('fs')
   , path = require('path')
   , normalize = path.normalize
@@ -27,6 +28,13 @@ var mime = require('mime-types');
 var parseUrl = require('parseurl');
 var resolve = require('path').resolve;
 
+/**
+ * Module exports.
+ * @public
+ */
+
+module.exports = serveIndex;
+
 /*!
  * Icon cache.
  */
@@ -66,35 +74,35 @@ var mediaType = {
  *
  * See Readme.md for documentation of options.
  *
- * @param {String} path
+ * @param {String} root
  * @param {Object} options
  * @return {Function} middleware
- * @api public
+ * @public
  */
 
-exports = module.exports = function serveIndex(root, options){
-  options = options || {};
+function serveIndex(root, options) {
+  var opts = options || {};
 
   // root required
-  if (!root) throw new TypeError('serveIndex() root path required');
+  if (!root) {
+    throw new TypeError('serveIndex() root path required');
+  }
 
   // resolve root to absolute and normalize
-  root = resolve(root);
-  root = normalize(root + sep);
+  var rootPath = normalize(resolve(root) + sep);
 
-  var hidden = options.hidden
-    , icons = options.icons
-    , view = options.view || 'tiles'
-    , filter = options.filter
-    , template = options.template || defaultTemplate
-    , stylesheet = options.stylesheet || defaultStylesheet;
+  var filter = opts.filter;
+  var hidden = opts.hidden;
+  var icons = opts.icons;
+  var stylesheet = opts.stylesheet || defaultStylesheet;
+  var template = opts.template || defaultTemplate;
+  var view = opts.view || 'tiles';
 
-  return function serveIndex(req, res, next) {
+  return function (req, res, next) {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
-      res.statusCode = 'OPTIONS' === req.method
-        ? 200
-        : 405;
+      res.statusCode = 'OPTIONS' === req.method ? 200 : 405;
       res.setHeader('Allow', 'GET, HEAD, OPTIONS');
+      res.setHeader('Content-Length', '0');
       res.end();
       return;
     }
@@ -106,19 +114,19 @@ exports = module.exports = function serveIndex(root, options){
     var originalDir = decodeURIComponent(originalUrl.pathname);
 
     // join / normalize from root dir
-    var path = normalize(join(root, dir));
+    var path = normalize(join(rootPath, dir));
 
     // null byte(s), bad request
     if (~path.indexOf('\0')) return next(createError(400));
 
     // malicious path
-    if ((path + sep).substr(0, root.length) !== root) {
+    if ((path + sep).substr(0, rootPath.length) !== rootPath) {
       debug('malicious path "%s"', path);
       return next(createError(403));
     }
 
     // determine ".." display
-    var showUp = normalize(resolve(path) + sep) !== root;
+    var showUp = normalize(resolve(path) + sep) !== rootPath;
 
     // check if we have a directory
     debug('stat "%s"', path);
@@ -148,11 +156,11 @@ exports = module.exports = function serveIndex(root, options){
 
         // content-negotiation
         var accept = accepts(req);
-        var type = accept.types(mediaTypes);
+        var type = accept.type(mediaTypes);
 
         // not acceptable
         if (!type) return next(createError(406));
-        exports[mediaType[type]](req, res, files, next, originalDir, showUp, icons, path, view, template, stylesheet);
+        serveIndex[mediaType[type]](req, res, files, next, originalDir, showUp, icons, path, view, template, stylesheet);
       });
     });
   };
@@ -162,23 +170,46 @@ exports = module.exports = function serveIndex(root, options){
  * Respond with text/html.
  */
 
-exports.html = function(req, res, files, next, dir, showUp, icons, path, view, template, stylesheet){
-  fs.readFile(template, 'utf8', function(err, str){
-    if (err) return next(err);
-    fs.readFile(stylesheet, 'utf8', function(err, style){
-      if (err) return next(err);
-      stat(path, files, function(err, stats){
-        if (err) return next(err);
-        files = files.map(function(file, i){ return { name: file, stat: stats[i] }; });
-        files.sort(fileSort);
-        if (showUp) files.unshift({ name: '..' });
-        str = str
-          .replace(/\{style\}/g, style.concat(iconStyle(files, icons)))
-          .replace(/\{files\}/g, html(files, dir, icons, view))
-          .replace(/\{directory\}/g, dir)
-          .replace(/\{linked-path\}/g, htmlPath(dir));
+serveIndex.html = function _html(req, res, files, next, dir, showUp, icons, path, view, template, stylesheet) {
+  var render = typeof template !== 'function'
+    ? createHtmlRender(template)
+    : template
 
-        var buf = new Buffer(str, 'utf8');
+  if (showUp) {
+    files.unshift('..');
+  }
+
+  // stat all files
+  stat(path, files, function (err, stats) {
+    if (err) return next(err);
+
+    // combine the stats into the file list
+    var fileList = files.map(function (file, i) {
+      return { name: file, stat: stats[i] };
+    });
+
+    // sort file list
+    fileList.sort(fileSort);
+
+    // read stylesheet
+    fs.readFile(stylesheet, 'utf8', function (err, style) {
+      if (err) return next(err);
+
+      // create locals for rendering
+      var locals = {
+        directory: dir,
+        displayIcons: Boolean(icons),
+        fileList: fileList,
+        path: path,
+        style: style,
+        viewName: view
+      };
+
+      // render html
+      render(locals, function (err, body) {
+        if (err) return next(err);
+
+        var buf = new Buffer(body, 'utf8');
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
         res.setHeader('Content-Length', buf.length);
         res.end(buf);
@@ -191,7 +222,7 @@ exports.html = function(req, res, files, next, dir, showUp, icons, path, view, t
  * Respond with application/json.
  */
 
-exports.json = function(req, res, files){
+serveIndex.json = function _json(req, res, files) {
   var body = JSON.stringify(files);
   var buf = new Buffer(body, 'utf8');
 
@@ -204,7 +235,7 @@ exports.json = function(req, res, files){
  * Respond with text/plain.
  */
 
-exports.plain = function(req, res, files){
+serveIndex.plain = function _plain(req, res, files) {
   var body = files.join('\n') + '\n';
   var buf = new Buffer(body, 'utf8');
 
@@ -213,11 +244,99 @@ exports.plain = function(req, res, files){
   res.end(buf);
 };
 
+/**
+ * Map html `files`, returning an html unordered list.
+ * @private
+ */
+
+function createHtmlFileList(files, dir, useIcons, view) {
+  var html = '<ul id="files" class="view-' + escapeHtml(view) + '">'
+    + (view == 'details' ? (
+      '<li class="header">'
+      + '<span class="name">Name</span>'
+      + '<span class="size">Size</span>'
+      + '<span class="date">Modified</span>'
+      + '</li>') : '');
+
+  html += files.map(function (file) {
+    var classes = [];
+    var isDir = file.stat && file.stat.isDirectory();
+    var path = dir.split('/').map(function (c) { return encodeURIComponent(c); });
+
+    if (useIcons) {
+      classes.push('icon');
+
+      if (isDir) {
+        classes.push('icon-directory');
+      } else {
+        var ext = extname(file.name);
+        var icon = iconLookup(file.name);
+
+        classes.push('icon');
+        classes.push('icon-' + ext.substring(1));
+
+        if (classes.indexOf(icon.className) === -1) {
+          classes.push(icon.className);
+        }
+      }
+    }
+
+    path.push(encodeURIComponent(file.name));
+
+    var date = file.stat && file.name !== '..'
+      ? file.stat.mtime.toLocaleDateString() + ' ' + file.stat.mtime.toLocaleTimeString()
+      : '';
+    var size = file.stat && !isDir
+      ? file.stat.size
+      : '';
+
+    return '<li><a href="'
+      + escapeHtml(normalizeSlashes(normalize(path.join('/'))))
+      + '" class="' + escapeHtml(classes.join(' ')) + '"'
+      + ' title="' + escapeHtml(file.name) + '">'
+      + '<span class="name">' + escapeHtml(file.name) + '</span>'
+      + '<span class="size">' + escapeHtml(size) + '</span>'
+      + '<span class="date">' + escapeHtml(date) + '</span>'
+      + '</a></li>';
+  }).join('\n');
+
+  html += '</ul>';
+
+  return html;
+}
+
+/**
+ * Create function to render html.
+ */
+
+function createHtmlRender(template) {
+  return function render(locals, callback) {
+    // read template
+    fs.readFile(template, 'utf8', function (err, str) {
+      if (err) return callback(err);
+
+      var body = str
+        .replace(/\{style\}/g, locals.style.concat(iconStyle(locals.fileList, locals.displayIcons)))
+        .replace(/\{files\}/g, createHtmlFileList(locals.fileList, locals.directory, locals.displayIcons, locals.viewName))
+        .replace(/\{directory\}/g, escapeHtml(locals.directory))
+        .replace(/\{linked-path\}/g, htmlPath(locals.directory));
+
+      callback(null, body);
+    });
+  };
+}
+
 /**
  * Sort function for with directories first.
  */
 
 function fileSort(a, b) {
+  // sort ".." to the top
+  if (a.name === '..' || b.name === '..') {
+    return a.name === b.name ? 0
+      : a.name === '..' ? -1 : 1;
+  }
+
   return Number(b.stat && b.stat.isDirectory()) - Number(a.stat && a.stat.isDirectory()) ||
     String(a.name).toLocaleLowerCase().localeCompare(String(b.name).toLocaleLowerCase());
 }
@@ -227,11 +346,19 @@ function fileSort(a, b) {
  */
 
 function htmlPath(dir) {
-  var curr = [];
-  return dir.split('/').map(function(part){
-    curr.push(encodeURIComponent(part));
-    return part ? '<a href="' + curr.join('/') + '">' + part + '</a>' : '';
-  }).join(' / ');
+  var parts = dir.split('/');
+  var crumb = new Array(parts.length);
+
+  for (var i = 0; i < parts.length; i++) {
+    var part = parts[i];
+
+    if (part) {
+      parts[i] = encodeURIComponent(part);
+      crumb[i] = '<a href="' + escapeHtml(parts.slice(0, i + 1).join('/')) + '">' + escapeHtml(part) + '</a>';
+    }
+  }
+
+  return crumb.join(' / ');
 }
 
 /**
@@ -296,7 +423,7 @@ function iconLookup(filename) {
  * Load icon images, return css string.
  */
 
-function iconStyle (files, useIcons) {
+function iconStyle(files, useIcons) {
   if (!useIcons) return '';
   var className;
   var i;
@@ -310,7 +437,7 @@ function iconStyle (files, useIcons) {
   for (i = 0; i < files.length; i++) {
     var file = files[i];
 
-    var isDir = '..' == file.name || (file.stat && file.stat.isDirectory());
+    var isDir = file.stat && file.stat.isDirectory();
     var icon = isDir
       ? { className: 'icon-directory', fileName: icons.folder }
       : iconLookup(file.name);
@@ -337,63 +464,6 @@ function iconStyle (files, useIcons) {
   return style;
 }
 
-/**
- * Map html `files`, returning an html unordered list.
- */
-
-function html(files, dir, useIcons, view) {
-  return '<ul id="files" class="view-' + view + '">'
-    + (view == 'details' ? (
-      '<li class="header">'
-      + '<span class="name">Name</span>'
-      + '<span class="size">Size</span>'
-      + '<span class="date">Modified</span>'
-      + '</li>') : '')
-    + files.map(function(file){
-    var isDir = '..' == file.name || (file.stat && file.stat.isDirectory())
-      , classes = []
-      , path = dir.split('/').map(function (c) { return encodeURIComponent(c); });
-
-    if (useIcons) {
-      classes.push('icon');
-
-      if (isDir) {
-        classes.push('icon-directory');
-      } else {
-        var ext = extname(file.name);
-        var icon = iconLookup(file.name);
-
-        classes.push('icon');
-        classes.push('icon-' + ext.substring(1));
-
-        if (classes.indexOf(icon.className) === -1) {
-          classes.push(icon.className);
-        }
-      }
-    }
-
-    path.push(encodeURIComponent(file.name));
-
-    var date = file.stat && file.name !== '..'
-      ? file.stat.mtime.toDateString() + ' ' + file.stat.mtime.toLocaleTimeString()
-      : '';
-    var size = file.stat && !isDir
-      ? file.stat.size
-      : '';
-
-    return '<li><a href="'
-      + normalizeSlashes(normalize(path.join('/')))
-      + '" class="'
-      + classes.join(' ') + '"'
-      + ' title="' + file.name + '">'
-      + '<span class="name">'+file.name+'</span>'
-      + '<span class="size">'+size+'</span>'
-      + '<span class="date">'+date+'</span>'
-      + '</a></li>';
-
-  }).join('\n') + '</ul>';
-}
-
 /**
  * Load and cache the given `icon`.
  *

package.json

@@ -1,23 +1,24 @@
 {
   "name": "serve-index",
   "description": "Serve directory listings",
-  "version": "1.5.3",
+  "version": "1.7.3",
   "author": "Douglas Christopher Wilson <doug@somethingdoug.com>",
   "license": "MIT",
   "repository": "expressjs/serve-index",
   "dependencies": {
-    "accepts": "~1.1.4",
-    "batch": "0.5.1",
-    "debug": "~2.1.0",
-    "http-errors": "~1.2.8",
-    "mime-types": "~2.0.4",
-    "parseurl": "~1.3.0"
+    "accepts": "~1.2.13",
+    "batch": "0.5.3",
+    "debug": "~2.2.0",
+    "escape-html": "~1.0.3",
+    "http-errors": "~1.3.1",
+    "mime-types": "~2.1.9",
+    "parseurl": "~1.3.1"
   },
   "devDependencies": {
     "after": "0.8.1",
-    "istanbul": "0.3.5",
-    "mocha": "~2.0.1",
-    "supertest": "~0.15.0"
+    "istanbul": "0.4.2",
+    "mocha": "2.3.4",
+    "supertest": "1.1.0"
   },
   "files": [
     "public/",
@@ -30,7 +31,7 @@
   },
   "scripts": {
     "test": "mocha --reporter spec --bail --check-leaks test/",
-    "test-cov": "istanbul cover node_modules/mocha/bin/_mocha -- --reporter dot --check-leaks test/",
-    "test-travis": "istanbul cover node_modules/mocha/bin/_mocha --report lcovonly -- --reporter spec --check-leaks test/"
+    "test-ci": "istanbul cover node_modules/mocha/bin/_mocha --report lcovonly -- --reporter spec --check-leaks test/",
+    "test-cov": "istanbul cover node_modules/mocha/bin/_mocha -- --reporter dot --check-leaks test/"
   }
 }

public/directory.html

@@ -75,7 +75,7 @@
   <body class="directory">
     <input id="search" type="text" placeholder="Search" autocomplete="off" />
     <div id="wrapper">
-      <h1>{linked-path}</h1>
+      <h1><a href="/">~</a>{linked-path}</h1>
       {files}
     </div>
   </body>

test/fixtures/users/#dir/tobi.txt

@@ -0,0 +1 @@
+ferret

test/test.js

@@ -109,7 +109,7 @@ describe('serveIndex(root)', function () {
         .get('/')
         .set('Accept', 'application/json')
         .expect('Content-Type', /json/)
-        .expect(/g# %3 o %2525 %37 dir/)
+        .expect(/g# %3 o & %2525 %37 dir/)
         .expect(/users/)
         .expect(/file #1\.txt/)
         .expect(/nums/)
@@ -128,7 +128,7 @@ describe('serveIndex(root)', function () {
         .set('Accept', 'text/html')
         .expect(200)
         .expect('Content-Type', 'text/html; charset=utf-8')
-        .expect(/<a href="\/g%23%20%253%20o%20%252525%20%2537%20dir"/)
+        .expect(/<a href="\/g%23%20%253%20o%20%26%20%252525%20%2537%20dir"/)
         .expect(/<a href="\/users"/)
         .expect(/<a href="\/file%20%231.txt"/)
         .expect(/<a href="\/todo.txt"/)
@@ -136,6 +136,20 @@ describe('serveIndex(root)', function () {
         .end(done);
       });
 
+      it('should property escape file names', function (done) {
+        var server = createServer()
+
+        request(server)
+        .get('/')
+        .set('Accept', 'text/html')
+        .expect(200)
+        .expect('Content-Type', 'text/html; charset=utf-8')
+        .expect(/<a href="\/foo%20%26%20bar"/)
+        .expect(/foo &amp; bar/)
+        .expect(bodyDoesNotContain('foo & bar'))
+        .end(done);
+      });
+
       it('should sort folders first', function (done) {
         var server = createServer()
 
@@ -145,15 +159,16 @@ describe('serveIndex(root)', function () {
         .expect(200)
         .expect('Content-Type', 'text/html; charset=utf-8')
         .end(function (err, res) {
-          if (err) throw err;
-          var urls = res.text.split(/<a href="([^"]*)"/).filter(function(s, i){ return i%2; });
+          if (err) done(err);
+          var body = res.text.split('</h1>')[1];
+          var urls = body.split(/<a href="([^"]*)"/).filter(function(s, i){ return i%2; });
           assert.deepEqual(urls, [
             '/%23directory',
             '/collect',
-            '/g%23%20%253%20o%20%252525%20%2537%20dir',
+            '/g%23%20%253%20o%20%26%20%252525%20%2537%20dir',
             '/users',
             '/file%20%231.txt',
-            '/foo%20bar',
+            '/foo%20%26%20bar',
             '/nums',
             '/todo.txt',
             '/%E3%81%95%E3%81%8F%E3%82%89.txt'
@@ -173,7 +188,7 @@ describe('serveIndex(root)', function () {
         .expect(200)
         .expect('Content-Type', 'text/plain; charset=utf-8')
         .expect(/users/)
-        .expect(/g# %3 o %2525 %37 dir/)
+        .expect(/g# %3 o & %2525 %37 dir/)
         .expect(/file #1.txt/)
         .expect(/todo.txt/)
         .expect(/さくら\.txt/)
@@ -255,7 +270,7 @@ describe('serveIndex(root)', function () {
     });
 
     it('should filter directory paths', function (done) {
-      var cb = after(3, done)
+      var cb = after(4, done)
       var server = createServer(fixtures, {'filter': filter})
 
       function filter(name, index, list, dir) {
@@ -289,6 +304,146 @@ describe('serveIndex(root)', function () {
     });
   });
 
+  describe('with "template" option', function () {
+    describe('when setting a custom template file', function () {
+      var server;
+      before(function () {
+        server = createServer(fixtures, {'template': __dirname + '/shared/template.html'});
+      });
+
+      it('should respond with file list', function (done) {
+        request(server)
+        .get('/')
+        .set('Accept', 'text/html')
+        .expect(/<a href="\/g%23%20%253%20o%20%26%20%252525%20%2537%20dir"/)
+        .expect(/<a href="\/users"/)
+        .expect(/<a href="\/file%20%231.txt"/)
+        .expect(/<a href="\/todo.txt"/)
+        .expect(200, done)
+      });
+
+      it('should respond with testing template sentence', function (done) {
+        request(server)
+        .get('/')
+        .set('Accept', 'text/html')
+        .expect(200, /This is the test template/, done)
+      });
+
+      it('should have default styles', function (done) {
+        request(server)
+        .get('/')
+        .set('Accept', 'text/html')
+        .expect(200, /ul#files/, done)
+      });
+
+      it('should list directory twice', function (done) {
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect(function (res) {
+          var occurances = res.text.match(/directory \/users\//g)
+          if (occurances && occurances.length === 2) return
+          throw new Error('directory not listed twice')
+        })
+        .expect(200, done)
+      });
+    });
+
+    describe('when setting a custom template function', function () {
+      it('should invoke function to render', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, 'This is a template.');
+        }});
+
+        request(server)
+        .get('/')
+        .set('Accept', 'text/html')
+        .expect(200, 'This is a template.', done);
+      });
+
+      it('should handle render errors', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(new Error('boom!'));
+        }});
+
+        request(server)
+        .get('/')
+        .set('Accept', 'text/html')
+        .expect(500, 'boom!', done);
+      });
+
+      it('should provide "directory" local', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, JSON.stringify(locals.directory));
+        }});
+
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect(200, '"/users/"', done);
+      });
+
+      it('should provide "displayIcons" local', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, JSON.stringify(locals.displayIcons));
+        }});
+
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect(200, 'false', done);
+      });
+
+      it('should provide "fileList" local', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, JSON.stringify(locals.fileList.map(function (file) {
+            file.stat = file.stat instanceof fs.Stats;
+            return file;
+          })));
+        }});
+
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect('[{"name":"..","stat":true},{"name":"#dir","stat":true},{"name":"index.html","stat":true},{"name":"tobi.txt","stat":true}]')
+        .expect(200, done);
+      });
+
+      it('should provide "path" local', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, JSON.stringify(locals.path));
+        }});
+
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect(200, JSON.stringify(path.join(fixtures, 'users/')), done);
+      });
+
+      it('should provide "style" local', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, JSON.stringify(locals.style));
+        }});
+
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect(200, /#files \.icon \.name/, done);
+      });
+
+      it('should provide "viewName" local', function (done) {
+        var server = createServer(fixtures, {'template': function (locals, callback) {
+          callback(null, JSON.stringify(locals.viewName));
+        }});
+
+        request(server)
+        .get('/users/')
+        .set('Accept', 'text/html')
+        .expect(200, '"tiles"', done);
+      });
+    });
+  });
+
   describe('when using custom handler', function () {
     describe('exports.html', function () {
       alterProperty(serveIndex, 'html', serveIndex.html)
@@ -436,6 +591,25 @@ describe('serveIndex(root)', function () {
       .end(done);
     });
 
+    it('should include link to parent directory', function (done) {
+      var server = createServer()
+
+      request(server)
+      .get('/users')
+      .end(function (err, res) {
+        if (err) return done(err);
+        var body = res.text.split('</h1>')[1];
+        var urls = body.split(/<a href="([^"]*)"/).filter(function(s, i){ return i%2; });
+        assert.deepEqual(urls, [
+          '/',
+          '/users/%23dir',
+          '/users/index.html',
+          '/users/tobi.txt'
+        ]);
+        done();
+      });
+    });
+
     it('should work for directory with #', function (done) {
       var server = createServer()
 
@@ -453,12 +627,26 @@ describe('serveIndex(root)', function () {
       var server = createServer()
 
       request(server)
-      .get('/g%23%20%253%20o%20%252525%20%2537%20dir/')
+      .get('/g%23%20%253%20o%20%26%20%252525%20%2537%20dir/')
       .set('Accept', 'text/html')
       .expect(200)
       .expect('Content-Type', 'text/html; charset=utf-8')
-      .expect(/<a href="\/g%23%20%253%20o%20%252525%20%2537%20dir"/)
-      .expect(/<a href="\/g%23%20%253%20o%20%252525%20%2537%20dir\/empty.txt"/)
+      .expect(/<a href="\/g%23%20%253%20o%20%26%20%252525%20%2537%20dir"/)
+      .expect(/<a href="\/g%23%20%253%20o%20%26%20%252525%20%2537%20dir\/empty.txt"/)
+      .end(done);
+    });
+
+    it('should property escape directory names', function (done) {
+      var server = createServer()
+
+      request(server)
+      .get('/g%23%20%253%20o%20%26%20%252525%20%2537%20dir/')
+      .set('Accept', 'text/html')
+      .expect(200)
+      .expect('Content-Type', 'text/html; charset=utf-8')
+      .expect(/<a href="\/g%23%20%253%20o%20%26%20%252525%20%2537%20dir"/)
+      .expect(/g# %3 o &amp; %2525 %37 dir/)
+      .expect(bodyDoesNotContain('g# %3 o & %2525 %37 dir'))
       .end(done);
     });
 
@@ -472,50 +660,6 @@ describe('serveIndex(root)', function () {
     });
   });
 
-  describe('when setting a custom template', function () {
-    var server;
-    before(function () {
-      server = createServer(fixtures, {'template': __dirname + '/shared/template.html'});
-    });
-
-    it('should respond with file list', function (done) {
-      request(server)
-      .get('/')
-      .set('Accept', 'text/html')
-      .expect(/<a href="\/g%23%20%253%20o%20%252525%20%2537%20dir"/)
-      .expect(/<a href="\/users"/)
-      .expect(/<a href="\/file%20%231.txt"/)
-      .expect(/<a href="\/todo.txt"/)
-      .expect(200, done)
-    });
-
-    it('should respond with testing template sentence', function (done) {
-      request(server)
-      .get('/')
-      .set('Accept', 'text/html')
-      .expect(200, /This is the test template/, done)
-    });
-
-    it('should have default styles', function (done) {
-      request(server)
-      .get('/')
-      .set('Accept', 'text/html')
-      .expect(200, /ul#files/, done)
-    });
-
-    it('should list directory twice', function (done) {
-      request(server)
-      .get('/users/')
-      .set('Accept', 'text/html')
-      .expect(function (res) {
-        var occurances = res.text.match(/directory \/users\//g)
-        if (occurances && occurances.length === 2) return
-        throw new Error('directory not listed twice')
-      })
-      .expect(200, done)
-    });
-  });
-
   describe('when setting a custom stylesheet', function () {
     var server;
     before(function () {