From 482519b7d1496c5ca79ec0e0a7c3f0926b308c8f Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 18 Jun 2026 11:08:24 +0200
Subject: [PATCH] hugo: fail the build on broken include references

The include shortcode previously called readFile directly, which renders
nothing when the target is missing instead of failing. That let renamed
or deleted snippets linger as silent no-ops (for example the stale
scout-early-access.md and compose/develop.md references).

Check fileExists first and errorf with the shortcode position when the
target is missing, mirroring the file/files shortcodes. Verified against
Hugo 0.163.0: valid includes still render; a missing target now fails the
build with the offending file and line.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 layouts/_shortcodes/include.html | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/layouts/_shortcodes/include.html b/layouts/_shortcodes/include.html
index 8beb853f2b..2faab47dd2 100644
--- a/layouts/_shortcodes/include.html
+++ b/layouts/_shortcodes/include.html
@@ -1,3 +1,17 @@
+{{/*
+  include shortcode — inlines a reusable snippet from content/includes.
+
+  Usage:
+    {{% include "root-errors.md" %}}
+    {{% include "compose/services.md" %}}
+
+  The argument is a path relative to content/includes. The build fails with
+  a clear message if the target does not exist, so a renamed or deleted
+  snippet surfaces immediately instead of silently rendering nothing.
+*/}}
 {{ $fileToInclude := .Get 0 }}
 {{ $filePath := printf "includes/%s" $fileToInclude }}
-{{ readFile $filePath | safeHTML }}
\ No newline at end of file
+{{ if not (fileExists $filePath) }}
+  {{- errorf "include shortcode: file %q not found: %s" $filePath .Position -}}
+{{ end }}
+{{ readFile $filePath | safeHTML }}