From 96d80d5e7482fbb9d4a4db9a1733481232ef7dbe Mon Sep 17 00:00:00 2001
From: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
Date: Wed, 27 Aug 2025 16:55:50 +0300
Subject: [PATCH 1/2] Stop docs generation if npm build:all script failed

Signed-off-by: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
---
 generator/_scripts/_run.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/generator/_scripts/_run.sh b/generator/_scripts/_run.sh
index 384711783..72bda7572 100755
--- a/generator/_scripts/_run.sh
+++ b/generator/_scripts/_run.sh
@@ -27,7 +27,7 @@ find $WRKDIR/documentation/hugo/content -name "*.include.markdown" -type f -dele
 cp -rn $WRKDIR/nt-docs/* $WRKDIR/documentation/hugo/
 cd $WRKDIR/documentation/hugo
 npm ci
-npm run build:all
+npm run build:all || exit 2
 
 cd $WRKDIR/documentation/generator
 mkdir -p $WRKDIR/documentation/generator/_site/assets/searchIndex

From d7d7f7fcadc1ee69a011b164bbe2fce71a096ba5 Mon Sep 17 00:00:00 2001
From: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
Date: Thu, 28 Aug 2025 13:13:27 +0300
Subject: [PATCH 2/2] Added codeblock pre-processor that adds value to one-word
 flags

Otherwise Hugo will fail to parse markdown with error: failed to parse Markdown attributes; you may need to quote the values

Signed-off-by: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
---
 .../_scripts/cfdoc_codeblock_resolver.py      | 62 +++++++++++++++++++
 generator/_scripts/cfdoc_preprocess.py        |  2 +
 2 files changed, 64 insertions(+)
 create mode 100644 generator/_scripts/cfdoc_codeblock_resolver.py

diff --git a/generator/_scripts/cfdoc_codeblock_resolver.py b/generator/_scripts/cfdoc_codeblock_resolver.py
new file mode 100644
index 000000000..763a353b8
--- /dev/null
+++ b/generator/_scripts/cfdoc_codeblock_resolver.py
@@ -0,0 +1,62 @@
+import re
+
+
+def run(config):
+    markdown_files = config["markdown_files"]
+    for file in markdown_files:
+        process(file)
+
+
+def process(file_path):
+    """
+    Reads a markdown file, searches for code block that have one-word flags
+    and replace with flag=value. Otherwise Hugo will fail to parse markdown
+    with error `failed to parse Markdown attributes; you may need to quote the values`
+    """
+    try:
+        # Read the file
+        with open(file_path, "r", encoding="utf-8") as file:
+            content = file.read()
+
+        # Find and replace codeblocks
+        transformed_content = transform_codeblocks(content)
+
+        # Write file if content was changed
+        if transformed_content != content:
+            with open(file_path, "w", encoding="utf-8") as file:
+                file.write(transformed_content)
+
+    except Exception as e:
+        print(f"Error processing file {file_path}: {str(e)}")
+        raise
+
+
+def transform_codeblocks(content):
+    pattern = re.compile(
+        r"^\s*```([a-zA-Z0-9_-]+)"  # language
+        r"[ \t]+\{([^}]*)\}\s*$",  # flags
+        re.MULTILINE,
+    )
+
+    def replacer(match):
+        language = match.group(1)
+        all_flags = match.group(2).strip()
+
+        if not all_flags:
+            return f"```{language}"
+
+        flag_parts = all_flags.split()
+        transformed_flags = []
+
+        for flag in flag_parts:
+            if "=" in flag:
+                # Already in key=value format, keep as is
+                transformed_flags.append(flag)
+            else:
+                # One-word flag, transform to flag=""
+                transformed_flags.append(f'{flag}=""')
+
+        flags_str = " ".join(transformed_flags)
+        return f"```{language} {{{flags_str}}}"
+
+    return pattern.sub(replacer, content)
diff --git a/generator/_scripts/cfdoc_preprocess.py b/generator/_scripts/cfdoc_preprocess.py
index 2bba28d80..5476637ae 100755
--- a/generator/_scripts/cfdoc_preprocess.py
+++ b/generator/_scripts/cfdoc_preprocess.py
@@ -32,6 +32,7 @@
 import cfdoc_references_resolver as references_resolver
 import cfdoc_shortcodes_resolver as shortcodes_resolver
 import cfdoc_images_path_resolver as images_path_resolver
+import cfdoc_codeblock_resolver as codeblock_resolver
 import sys
 import os
 
@@ -48,3 +49,4 @@
 references_resolver.run(config)
 shortcodes_resolver.run(config)
 images_path_resolver.run(config)
+codeblock_resolver.run(config)