add suggestions; update userguide

Author: aimeeu

layouts/shortcodes/readfile.html

@@ -24,8 +24,8 @@
 {{ end }}
 
 
-{{/* If the file exists, read it and highlight it if it's code. Throw an error
-if the file is not found */}}
+{{/* If the file exists, read it and highlight it if it's code.
+Throw a compile error or print an error on the page if the file is not found */}}
 
 {{ if fileExists ($.Scratch.Get "filepath") }}
   {{ if eq (.Get "code") "true" }}
@@ -34,4 +34,8 @@
   {{ else }}
     {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}}
   {{ end }}
-{{ else }}{{- errorf "File not found: %s %s" ($.Scratch.Get "filepath") .Position -}}{{ end }}
+{{ else if eq (.Get "draft") "true" }}
+
+  <p style="color: #D74848"><b><i>The file <code>{{ $.Scratch.Get "filepath" }}</code> was not found.</i></b></p> 
+
+{{ else }}{{- errorf "Shortcode %q: file %q not found at %s" .Name ($.Scratch.Get "filepath") .Position -}}{{ end }}

userguide/content/en/docs/adding-content/shortcodes/index.md

@@ -679,14 +679,28 @@ under the parent file's working directory are supported.
 For files outside the current working directory you can use an absolute path
 starting with `/`. The root directory is the `/content` folder.
 
-
-
 | Parameter        | Default    | Description  |
 | ---------------- |------------| ------------|
 | file | | Path of external file|
 | code | false | Boolean value. If `true` the contents is treated as code|
 | lang | plain text | Programming language |
 
+### Error reporting
+
+If the shortcode can't find the specified file, the shortcode throws a compile error.
+
+In the following example, Hugo throws a compile error if it can't find `includes/deploy.yml`:
+
+```go-html-template
+{{</* readfile file="includes/deploy.yaml" code="true" lang="yaml" */>}}
+```
+
+Alternately, Hugo you can display a message on the rendered page instead of throwing a compile error. Add `draft="true"` as a parameter. For example:
+
+```go-html-template
+{{</* readfile file="includes/deploy.yaml" code="true" lang="yaml" draft="true" */>}}
+```
+
 ## Conditional text
 
 The `conditional-text` shortcode allows you to show or hide parts of your content depending on the value of the `buildCondition` parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds.