From e456e34bdbde058243eb0a5d3c0017748639e08e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?=
 <bjorn.erik.pedersen@gmail.com>
Date: Wed, 7 Nov 2018 10:20:08 +0100
Subject: [PATCH] docs: Document shortcode error handling

Closes https://github.com/gohugoio/hugoDocs/issues/660
---
 .../en/templates/shortcode-templates.md        | 18 ++++++++++++++++++
 docs/content/en/variables/shortcodes.md        |  6 ++++++
 2 files changed, 24 insertions(+)

diff --git a/docs/content/en/templates/shortcode-templates.md b/docs/content/en/templates/shortcode-templates.md
index cf0d7bc6f..d5ea49399 100644
--- a/docs/content/en/templates/shortcode-templates.md
+++ b/docs/content/en/templates/shortcode-templates.md
@@ -346,6 +346,24 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
 <img src="/images/three.jpg">
 ```
 
+
+## Error Handling in Shortcodes
+
+Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
+
+```bash
+{{ with .Get "name" }}
+{{ else }}
+{{ errorf "missing value for param 'name': %s" .Position }}
+{{ end }}
+```
+
+When the above fails, you will see an `ERROR` log similar to the below:
+
+```bash
+ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
+```
+
 ## More Shortcode Examples
 
 More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes].
diff --git a/docs/content/en/variables/shortcodes.md b/docs/content/en/variables/shortcodes.md
index 3484df7a0..10b779396 100644
--- a/docs/content/en/variables/shortcodes.md
+++ b/docs/content/en/variables/shortcodes.md
@@ -26,6 +26,12 @@ toc: false
 .Parent
 : provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root.
 
+.Position
+: Contains [filename and position](https://godoc.org/github.com/gohugoio/hugo/common/text#Position) for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See [Error Handling in Shortcodes](/templates/shortcode-templates/#error-handling-in-shortcodes).
+
+
+
+
 .IsNamedParams
 : boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes]