HUGO

  • News
  • Docs
  • Themes
  • Community
  • GitHub
Star

What's on this Page

    • Traverse Local Files
    • Use readDir
      • readDir Example: List Directory Files
    • Use readFile
      • readFile Example: Add a Project File to Content
TEMPLATES

Local File Templates

Hugo’s readerDir and readFile functions make it easy to traverse your project’s directory structure and write file contents to your templates.

Traverse Local Files

With Hugo’s readDir and readFile template functions, you can traverse your website’s files on your server.

Use readDir

The readDir function returns an array of os.FileInfo. It takes the file’s path as a single string argument. This path can be to any directory of your website (i.e., as found on your server’s file system).

Whether the path is absolute or relative does not matter because—at least for readDir—the root of your website (typically ./public/) in effect becomes both:

  1. The file system root
  2. The current working directory

readDir Example: List Directory Files

This shortcode creates a link to each of the files in a directory—display as the file’s basename—along with the file’s size in bytes.

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 }}" target="_blank"> {{ .Name }}</a></td>
    </tr>
{{- end }}
</table>

You can then call the shortcode as follows inside of your content’s markup:

{{< directoryindex path="/static/css" pathURL="/css" >}}

The above shortcode is part of the code for the Hugo docs. Here it lists this site’s CSS files:

Size in bytes Name
134516 app.bundle.js
108794 main.css

The initial slash / in pathURL is important in the directoryindex shortcode. Otherwise, pathURL becomes relative to the current web page.

Use readFile

The readfile function reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. readFile takes the file, including path, as an argument passed to the function.

To use the readFile function in your templates, make sure the path is relative to your Hugo project’s root directory:

{{ readFile "/content/templates/local-file-templates" }}

readFile Example: Add a Project File to Content

As readFile is a function, it is only available to you in your templates and not your content. However, we can create a simple shortcode template that calls readFile, passes the first argument through the function, and then allows an optional second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows:

{{< readfile file="/path/to/local/file.txt" markdown="true" >}}

If you are going to create custom shortcodes with readFile for a theme, note that usage of the shortcode will refer to the project root and not your themes directory.

Here is the templating for our new readfile shortcode:

layouts/shortcodes/readfile.html

{{$file := .Get "file"}}
{{- if eq (.Get "markdown") "true" -}}
{{- $file  | readFile | markdownify -}}
{{- else -}}
{{ $file  | readFile | safeHTML }}
{{- end -}}

This readfile shortcode is also part of the Hugo docs. So is testing.txt, which we will call in this example by passing it into our new readfile shortcode as follows:

{{< readfile file="/content/readfiles/testing.txt" >}}

The output “string” for this shortcode declaration will be the following:

##### Hello World!

Testing one, **two**, *three*. Don't delete this sample file used in the [templates](/templates/) section of the Hugo docs.

However, if we want Hugo to pass this string through Blackfriday, we should add the markdown="true" optional parameter:

{{< readfile file="/content/readfiles/testing.txt" markdown="true" >}}

And here is the result as called directly in the Hugo docs and rendered for display:

Hello World!

Testing one, two, three. Don’t delete this sample file used in the templates section of the Hugo docs.

See Also

  • readFile
  • Directory Structure
  • Create a Theme
  • Install and Use Themes
  • Customize a Theme
  • About Hugo
    • Overview
    • Hugo Features
    • The Benefits of Static
    • Roadmap
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • Themes
    • Themes Overview
    • Install and Use Themes
    • Customize a Theme
    • Create a Theme
  • Content Management
    • Content Management Overview
    • Organization
    • Supported Content Formats
    • Front Matter
    • Shortcodes
    • Related Content
    • Sections
    • Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .Param
    • .Scratch
    • .Unix
    • Math
    • absLangURL
    • absURL
    • after
    • apply
    • base64
    • chomp
    • countrunes
    • countwords
    • dateFormat
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • findRE
    • first
    • ge
    • getenv
    • gt
    • hasPrefix
    • highlight
    • htmlEscape
    • htmlUnescape
    • humanize
    • i18n
    • imageConfig
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang.NumFmt
    • last
    • le
    • lower
    • lt
    • markdownify
    • md5
    • ne
    • now
    • partialCached
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • relLangURL
    • relURL
    • relref
    • render
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • time
    • title
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • CLI
  • Troubleshooting
    • Troubleshoot
    • Accented Characters in URLs
    • Build Performance
    • EOF Error
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Host-Agnostic Deploys with Nanobox
    • Host on Netlify
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on Bitbucket
    • Deployment with Wercker
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
“Local File Templates” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page
By the Hugo Authors

The Hugo logos are copyright © Steve Francia 2013–2017.

The Hugo Gopher is based on an original work by Renée French.

  • File an Issue
  • Get Help
  • Discuss the Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays
  • News
  • Docs
  • Themes
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Themes
  • Content Management
  • Templates
  • Functions
  • Variables
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute