docs: Add support for addon keywords to Markdown

man/build_keywords.py

@@ -19,6 +19,7 @@
 """
 
 import os
+import re
 import sys
 import glob
 
@@ -95,11 +96,28 @@ def build_keywords(ext):
         else:
             keys = []
             for line in lines:
-                if "keywords:" in line:
-                    keys = [x.strip() for x in line.split(":", 1)[1].strip().split(",")]
+                match = re.match(r"keywords:\s*(.*)", line)
+                if match:
+                    text = match.group(1)
+                    if not text:
+                        print(
+                            f"Warning: Empty keyword list in {fname}", file=sys.stderr
+                        )
+                        break
+                    keys = [item.strip() for item in text.split(",")]
                     break
 
+        # No keywords in file is allowed because some non-tool pages don't have
+        # keywords, so we don't check for that specifically (only set but broken
+        # keywords are flagged).
+
         for key in keys:
+            if not key:
+                print(
+                    f"Warning: Empty keyword in {fname}, all keywords: {keys}",
+                    file=sys.stderr,
+                )
+                continue
             if key not in keywords.keys():
                 keywords[key] = []
                 keywords[key].append(fname)

utils/mkmarkdown.py

@@ -145,12 +145,48 @@ def extract_yaml_header(md_content):
     return yaml_header, content
 
 
-def merge_md_files(md1, md2):
+def modify_keyword_links(text, prefix):
+    """Modify links in the Keywords section by adding a prefix to the link URLs.
+
+    Returns input text unchanged if no Keywords section found or if prefix is not set.
+
+    :param text: The markdown text as a string
+    :param prefix: The prefix to add to the links (can be empty or None)
+    :return: The modified markdown text
+    """
+    if not prefix:
+        return text
+
+    # Find the Keywords section
+    # Level is determined by the number of hashes.
+    keywords_match = re.search(
+        r"##\s*Keywords(.*?)(##\s*|$)", text, re.DOTALL | re.IGNORECASE
+    )
+    if not keywords_match:
+        return text
+    keywords_content = keywords_match.group(1)
+
+    # Match Markdown links and add prefix.
+    modified_keywords_content = re.sub(
+        r"(\[.*?\]\()([^\)]+)(\))",
+        lambda m: f"{m.group(1)}{prefix}{m.group(2)}{m.group(3)}",
+        keywords_content,
+    )
+    # Replace the original Keywords section with the modified one.
+    return text.replace(keywords_content, modified_keywords_content)
+
+
+def merge_md_files(md1, md2, content_modifier1, content_modifier2):
     """Merge two markdown files by concatenating their YAML headers and content."""
     yaml1, content1 = extract_yaml_header(md1)
     yaml2, content2 = extract_yaml_header(md2)
 
-    # Contatenate the headers.
+    if content_modifier1:
+        content1 = content_modifier1(content1)
+    if content_modifier2:
+        content2 = content_modifier2(content2)
+
+    # Concatenate the headers.
     yaml_items = []
     if yaml1:
         yaml_items.append(yaml1)
@@ -178,12 +214,22 @@ def main():
 """
     )
 
+    def modify_generated(text):
+        prefix = os.getenv("HTML_PAGE_FOOTER_PAGES_PATH") or None
+        return modify_keyword_links(text, prefix=prefix)
+
     # process header/usage generated by --md-description
     tool_generated = read_file(tmp_file)
     # process body
     source_code = read_file(src_file)
     # combine
-    for item in merge_md_files(tool_generated, source_code):
+    items = merge_md_files(
+        tool_generated,
+        source_code,
+        content_modifier1=modify_generated,
+        content_modifier2=None,
+    )
+    for item in items:
         if not item:
             continue
         sys.stdout.write(item)