diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-11-07 10:20:08 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-11-07 10:38:58 +0100 |
commit | e456e34bdbde058243eb0a5d3c0017748639e08e (patch) | |
tree | 5c3db47595b8a18ac5e476112330e48192181bee /docs | |
parent | 5d14d04ac678ad24e4946ed2a581ab71b3834def (diff) |
docs: Document shortcode error handling
Closes https://github.com/gohugoio/hugoDocs/issues/660
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/en/templates/shortcode-templates.md | 18 | ||||
-rw-r--r-- | docs/content/en/variables/shortcodes.md | 6 |
2 files changed, 24 insertions, 0 deletions
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] |