From 291fd233d78f2a107bccc798e60fdb0a58672595 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimeeu.opensource@gmail.com>
Date: Fri, 3 Mar 2023 14:59:31 -0600
Subject: [PATCH 1/2] Shortcodes: Update readfile to throw compile error

Update readfile shortcode to throw a compile error when the
file is not found. Currenlty the shortcode prints a message on the
UI, which presents a problem when refactoring a docs site. A UI
message requires visual conformation and is easy to miss when moving
or renaming directories.
---
 layouts/shortcodes/readfile.html | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html
index ce05aef322..7921a1c7c4 100644
--- a/layouts/shortcodes/readfile.html
+++ b/layouts/shortcodes/readfile.html
@@ -34,8 +34,4 @@
   {{ else }}
     {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}}
   {{ end }}
-{{ else }}
-
-<p style="color: #D74848"><b><i>The file <code>{{ $.Scratch.Get "filepath" }}</code> was not found.</i></b></p>
-
-{{ end }}
+{{ else }}{{- errorf "File not found: %s %s" ($.Scratch.Get "filepath") .Position -}}{{ end }}

From 3b4ef220e6761bedcb1e61405c477121152fb31b Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimeeu.opensource@gmail.com>
Date: Tue, 18 Apr 2023 13:04:01 -0500
Subject: [PATCH 2/2] add suggestions; update userguide

---
 layouts/shortcodes/readfile.html               | 10 +++++++---
 .../en/docs/adding-content/shortcodes/index.md | 18 ++++++++++++++++--
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html
index 7921a1c7c4..0a9b5a95ae 100644
--- a/layouts/shortcodes/readfile.html
+++ b/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 }}
diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md
index 2b99b71d52..c3a2cb16a7 100644
--- a/userguide/content/en/docs/adding-content/shortcodes/index.md
+++ b/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.