Traversing Local Files

Using Hugo’s function readDir, you can traverse your web site’s files on your server.

Using readDir

The readDir function returns an array of 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).

Whether the path is absolute or relative makes no difference, because—at least for readDir—the root of your web site (typically ./public/) in effect becomes both:

  1. The filesystem root; and
  2. The current working directory.

New Shortcode

So, let’s create a new shortcode using readDir:

layouts/shortcodes/directoryindex.html

{{- $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>

For the files in any given directory, this shortcode usefully lists their basenames and sizes, while providing links to them.

Already—actually—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.)

Size in bytes Name
1440 bootstrap-additions-gohugo.css
2629 bootstrap-changes-gohugo.css
22485 bootstrap-stripped-gohugo.css
2368 content-style.css
1277 home-page-style-responsive.css
3542 home-page-style.css
2828 hugofont.css
1117 style-responsive.css
13897 style.css

This is the call that rendered the above output:

{{< 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.