1 files changed, 32 insertions, 9 deletions
diff --git a/docs/content/en/functions/readdir.md b/docs/content/en/functions/readdir.md
index a70e1f8bc..70fe7b66c 100644
--- a/docs/content/en/functions/readdir.md
+++ b/docs/content/en/functions/readdir.md
@@ -1,28 +1,51 @@
 ---
 title: readDir
-description: Gets a directory listing from a directory relative to the current working directory.
-date: 2017-02-01
+description: Returns an array of FileInfo structures sorted by filename, one element for each directory entry.
 publishdate: 2017-02-01
-lastmod: 2017-02-01
+lastmod: 2021-11-26
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 keywords: [files]
-signature: ["readDir PATH"]
+signature: ["os.ReadDir PATH", "readDir PATH"]
 workson: []
 hugoversion:
-relatedfuncs: [readFile]
+relatedfuncs: ['os.FileExists','os.ReadFile','os.Stat']
 deprecated: false
 aliases: []
 ---
+The `os.ReadDir` function resolves the path relative to the root of your project directory. A leading path separator (`/`) is optional.
 
-If your current project working directory has a single file named `README.txt`:
+With this directory structure:
 
+```text
+content/
+├── about.md
+├── contact.md
+└── news/
+    ├── article-1.md
+    └── article-2.md
 ```
-{{ range (readDir ".") }}{{ .Name }}{{ end }} → "README.txt"
+
+This template code:
+
+```go-html-template
+{{ range os.ReadDir "content" }}
+  {{ .Name }} --> {{ .IsDir }}
+{{ end }}
+```
+
+Produces:
+
+```html
+about.md --> false
+contact.md --> false
+news --> true
 ```
 
-For more information on using `readDir` and `readFile` in your templates, see [Local File Templates][local].
+Note that `os.ReadDir` is not recursive.
+
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
 
-[local]: /templates/files/
+For more information on using `readDir` and `readFile` in your templates, see [Local File Templates]({{< relref "/templates/files" >}}).