From 0d1e96701fd3907d0a3e15e068925fe42ba3f662 Mon Sep 17 00:00:00 2001
From: "Mark D. Blackwell" <markdblackwell01@gmail.com>
Date: Sat, 10 Sep 2016 18:23:23 -0400
Subject: [PATCH] docs: Improve Traversing Local Files

---
 docs/content/extras/localfiles.md           | 66 +++++++++++----------
 docs/layouts/shortcodes/directoryindex.html | 13 ++++
 docs/layouts/shortcodes/fileindex.html      | 16 -----
 docs/layouts/shortcodes/readfile.html       |  1 +
 4 files changed, 50 insertions(+), 46 deletions(-)
 create mode 100644 docs/layouts/shortcodes/directoryindex.html
 delete mode 100644 docs/layouts/shortcodes/fileindex.html
 create mode 100644 docs/layouts/shortcodes/readfile.html

diff --git a/docs/content/extras/localfiles.md b/docs/content/extras/localfiles.md
index 2b3549a02..d89ead098 100644
--- a/docs/content/extras/localfiles.md
+++ b/docs/content/extras/localfiles.md
@@ -1,7 +1,7 @@
 ---
 aliases:
 - /doc/localfiles/
-lastmod: 2015-08-07
+lastmod: 2016-09-12
 date: 2015-06-12
 menu:
   main:
@@ -12,41 +12,47 @@ prev: /extras/urls
 title: Traversing Local Files
 weight: 110
 ---
-
 ## Traversing Local Files
 
-Hugo includes a way to traverse local files.
-This is done using the 'readDir' function.
+Using Hugo's function `readDir`,
+you can traverse your web site's files on your server.
+## Using _readDir_
 
-## Using readDir
+The `readDir` function returns an array
+of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo).
+It takes a single, string argument: a path.
+This path can be to any directory of your web site
+(as found on your server's filesystem).
 
-readDir takes a single string input that is relative to the root directory of the site. It returns an array of [os.FileInfo](https://golang.org/pkg/os/#FileInfo)
+Whether the path is absolute or relative makes no difference,
+because&mdash;at least for `readDir`&mdash;the root of your web site (typically `./public/`)
+in effect becomes both:
 
-Let's create a shortcode to build a file index with links using readDir.
+1. The filesystem root; and
+1. The current working directory.
 
-'fileindex.html'
+## New Shortcode
 
-    <table style="width=100%">
-    <th>Size in bytes</th>
-    <th>Name</th>
-    {{$dir := .Get "dir"}}
-    {{ $url := .Get "baseurl" }}
-    
-    {{ $files := readDir $dir }}
-        {{ range $files }}
-    			<tr>
-                    <td>{{.Size}}</td>
-                    <td>
-                        <a href="{{$url}}{{.Name | urlize }}"> {{.Name}}</a>
-                        </td>
-                </tr>
-    	 {{ end }}
-    </table>
-    
-Now lets use it to list the css files used on this site
+So, let's create a new shortcode using `readDir`:
 
-    {{</* fileindex dir="static/css" baseurl="/css/" */>}}
+**layouts/shortcodes/directoryindex.html**
+```html
+{{< readfile "layouts/shortcodes/directoryindex.html" >}}
+```
+For the files in any given directory,
+this shortcode usefully lists their basenames and sizes,
+while providing links to them.
 
-Is rendered as:
-
-{{< fileindex dir="static/css/" baseurl="/css/">}}
+Already&mdash;actually&mdash;this shortcode
+has been included in this very web site.
+So, let's list some of its CSS files.
+(If you click on their names, you can reveal the contents.)
+{{<   directoryindex path="/static/css" pathURL="/css"   >}}
+<br />
+This is the call that rendered the above output:
+```html
+{{</* directoryindex path="/static/css" pathURL="/css" */>}}
+```
+By the way,
+regarding the pathURL argument, the initial slash `/` is important.
+Otherwise, it becomes relative to the current web page.
diff --git a/docs/layouts/shortcodes/directoryindex.html b/docs/layouts/shortcodes/directoryindex.html
new file mode 100644
index 000000000..02a4efadc
--- /dev/null
+++ b/docs/layouts/shortcodes/directoryindex.html
@@ -0,0 +1,13 @@
+{{- $pathURL := .Get "pathURL" -}}
+{{- $path := .Get "path" -}}
+{{- $files := readDir $path -}}
+<table>
+    <th>Size in bytes</th>
+    <th>Name</th>
+{{- range $files }}
+    <tr>
+        <td>{{ .Size }}</td>
+        <td><a href="{{ $pathURL }}{{ .Name | relURL }}"> {{ .Name }}</a></td>
+    </tr>
+{{- end }}
+</table>
diff --git a/docs/layouts/shortcodes/fileindex.html b/docs/layouts/shortcodes/fileindex.html
deleted file mode 100644
index 26b903f6a..000000000
--- a/docs/layouts/shortcodes/fileindex.html
+++ /dev/null
@@ -1,16 +0,0 @@
-<table style="width=100%">
-<th>Size in bytes</th>
-<th>Name</th>
-{{$dir := .Get "dir"}}
-{{ $url := .Get "baseurl" }}
-
-{{ $files := readDir $dir }}
-    {{ range $files }}
-			<tr>
-                <td>{{.Size}}</td>
-                <td>
-                    <a href="{{$url}}{{.Name | urlize }}"> {{.Name}}</a>
-                    </td>
-            </tr>
-	 {{ end }}
-</table>
diff --git a/docs/layouts/shortcodes/readfile.html b/docs/layouts/shortcodes/readfile.html
new file mode 100644
index 000000000..f5b3459bf
--- /dev/null
+++ b/docs/layouts/shortcodes/readfile.html
@@ -0,0 +1 @@
+{{- .Get 0 | readFile -}}