Support fallback markdown includes for missing files

Author: JohT

scripts/markdown/embedMarkdownIncludes.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# Processes template markdown (sysin) replacing placeholders like "<!-- include:intro.md -->" with the contents of the specified markdown files. The files to include needs to be in the "includes" subdirectory.
+# Processes template markdown (sysin) replacing placeholders like "<!-- include:intro.md -->" or "<!-- include:intro.md|fallback.md -->" with the contents of the specified markdown files. The files to include needs to be in the "includes" subdirectory.
 # Can take an optional input for the directory that contains the markdown files to be included/embedded (defaults to "includes").
 
 # Fail on any error ("-e" = exit on first error, "-o pipefail" exist on errors within piped commands)
@@ -34,33 +34,48 @@ echo -n "${markdown_template}" | awk -v includes_directory="${includes_directory
     return 1
   }
 
-  function include_file(path,   fullpath, line) {
-    fullpath = includes_directory "/" path
-
+  function try_include(path,   fullpath, line) {
     if (!is_safe(path)) {
       print "ERROR: illegal include path: " path > "/dev/stderr"
       exit 1
     }
-
+    fullpath = includes_directory "/" path
     if ((getline test < fullpath) < 0) {
-      print "ERROR: missing file " fullpath > "/dev/stderr"
-      exit 1
+      return 0  # not found
     }
     close(fullpath)
 
     while ((getline line < fullpath) > 0) {
       print line
     }
     close(fullpath)
+    return 1
+  }
+
+  function include_file(spec,   n, parts, i, success) {
+    n = split(spec, parts, /\|/)
+    success = 0
+    for (i = 1; i <= n; i++) {
+      gsub(/^[ \t]+|[ \t]+$/, "", parts[i])   # trim
+      if (parts[i] == "") continue
+      if (try_include(parts[i])) {
+        success = 1
+        break
+      }
+    }
+    if (!success) {
+      print "ERROR: missing include file(s): " spec > "/dev/stderr"
+      exit 1
+    }
   }
 
   {
-    # Look for the include marker using index+substr (portable)
-    if ($0 ~ /<!-- include:/) {
+    # Look for the include marker
+    if ($0 ~ /<!--[ \t]*include:/) {
       start = index($0, "include:") + 8
       end   = index($0, "-->")
       fname = substr($0, start, end - start)
-      gsub(/^[ \t]+|[ \t]+$/, "", fname)   # trim spaces
+      gsub(/^[ \t]+|[ \t]+$/, "", fname)
 
       include_file(fname)
     } else {
@@ -69,4 +84,5 @@ echo -n "${markdown_template}" | awk -v includes_directory="${includes_directory
   }
 '
 
+
 #echo "embedMarkdownIncludes: $(date +'%Y-%m-%dT%H:%M:%S%z') Successfully finished." >&2

scripts/markdown/testEmbedMarkdownIncludes.sh

@@ -105,9 +105,31 @@ set -o errexit
 if [ ${exitCode} -eq 0 ]; then
   fail "2.) Test failed: Expected an error due to missing include file, but the script succeeded."
 fi
-if [[ "${errorOutput}" != *"ERROR: missing file"* ]]; then
+if [[ "${errorOutput}" != *"ERROR: missing include file"* ]]; then
   fail "2.) Test failed: Expected error message to contain 'ERROR: missing file', but got '${errorOutput}'."
 fi
 
+# ------------------------------------------------------------
+# Test case                                                 --
+# ------------------------------------------------------------
+echo "testEmbedMarkdownIncludes: 4.) The fallback include is used when the main include is missing"
+
+# - Setup
+testFallbackIncludeFileName="testFallbackInclude.md"
+echo "<!-- include:nonExistingInclude|${testFallbackIncludeFileName} -->" > "${testMarkdownTemplate}"
+
+testFallbackIncludeFile="includes/${testFallbackIncludeFileName}"
+expected_test_include_content="This is the included content from the fallback include."
+echo "${expected_test_include_content}" > "${temporaryTestDirectory}/${testFallbackIncludeFile}"
+
+# - Execute script under test
+embeddedContent=$(cd "${temporaryTestDirectory}"; cat "${testMarkdownTemplate}" | "${MARKDOWN_SCRIPTS_DIR}/embedMarkdownIncludes.sh")
+
+# - Verify results
+if [ "${embeddedContent}" != "${expected_test_include_content}" ]; then
+  fail "4.) Test failed: Expected embedded content to be '${expected_test_include_content}', but got '${embeddedContent}'."
+fi
+
+
 successful
 return 0