fix: update docs-convert to handle more escaping

Also remove trailing whitespace on generated docs

Signed-off-by: Justin Garrison <justin.garrison@siderolabs.com>

Author: rothgar

docs-convert/main.go

@@ -34,6 +34,11 @@ func convertFile(srcPath, dstPath string) error {
 		return err
 	}
 
+	// Trim excessive trailing blank lines (keep at most 1)
+	for len(lines) > 0 && strings.TrimSpace(lines[len(lines)-1]) == "" {
+		lines = lines[:len(lines)-1]
+	}
+
 	// Check if this is the v1alpha1/config file or cli file
 	isConfigFile := strings.Contains(dstPath, "v1alpha1/config.mdx") || strings.Contains(dstPath, "v1alpha1\\config.mdx")
 	isCliFile := strings.HasSuffix(dstPath, "/cli.mdx") || strings.HasSuffix(dstPath, "\\cli.mdx")
@@ -273,29 +278,53 @@ func escapeAngleBracketPlaceholders(line string) string {
 				// Extract the content between < and >
 				content := line[i+1 : end]
 				// Check if it's likely a placeholder or text that should not be parsed as HTML
-				// Known HTML tags we want to preserve: a, br, p, Accordion, details, summary, pre, code and their closing tags
+				// Known HTML tags we want to preserve: a, br, p, Accordion, details, summary, pre, code, td, th, tr, table, thead, tbody and their closing tags
 				isKnownTag := strings.HasPrefix(content, "a ") ||
+					content == "a" ||
 					strings.HasPrefix(content, "br") ||
-					strings.HasPrefix(content, "p") ||
+					content == "p" ||
+					strings.HasPrefix(content, "p ") ||
 					strings.HasPrefix(content, "Accordion") ||
 					strings.HasPrefix(content, "details") ||
 					strings.HasPrefix(content, "summary") ||
 					strings.HasPrefix(content, "pre") ||
+					content == "pre" ||
 					strings.HasPrefix(content, "code") ||
+					content == "code" ||
+					strings.HasPrefix(content, "td") ||
+					content == "td" ||
+					strings.HasPrefix(content, "th") ||
+					content == "th" ||
+					strings.HasPrefix(content, "tr") ||
+					content == "tr" ||
+					strings.HasPrefix(content, "table") ||
+					strings.HasPrefix(content, "thead") ||
+					strings.HasPrefix(content, "tbody") ||
 					content == "/a" ||
 					content == "/br" ||
 					content == "/p" ||
 					content == "/Accordion" ||
 					content == "/details" ||
 					content == "/summary" ||
 					content == "/pre" ||
-					content == "/code"
+					content == "/code" ||
+					content == "/td" ||
+					content == "/th" ||
+					content == "/tr" ||
+					content == "/table" ||
+					content == "/thead" ||
+					content == "/tbody"
 
 				// If it's not a known HTML tag, escape using JSX expressions
 				if !isKnownTag {
 					result += `{"<"}` + content + `{">"}`
 					i = end + 1
 					continue
+				} else {
+					// For known HTML tags, copy the entire tag at once
+					result += line[i : end+1]
+					i = end + 1
+					continue
 				}
 			}
 		}
@@ -469,13 +498,88 @@ func processCellContent(content string) string {
 	// Escape angle bracket placeholders
 	content = escapeAngleBracketPlaceholders(content)
 
+	// Wrap technical patterns in backticks for code formatting
+	content = wrapTechnicalPatternsInBackticks(content)
+
 	// Collapse all whitespace (including newlines) into single spaces for MDX compatibility
 	// This prevents parsing errors with multi-line content in <td> tags
 	content = strings.Join(strings.Fields(content), " ")
 
 	return content
 }
 
+// wrapTechnicalPatternsInBackticks wraps patterns like memory_{some,full}_{avg10,avg60,avg300} in backticks
+func wrapTechnicalPatternsInBackticks(content string) string {
+	// Pattern: word characters, underscores, with {option1,option2,...} expansions
+	// Examples: memory_{some,full}_{avg10,avg60,avg300,total}
+	// Look for: starts with letter/underscore, contains {, }, commas, and underscores
+
+	result := ""
+	i := 0
+	for i < len(content) {
+		// Skip if already in backticks
+		if i > 0 && content[i-1] == '`' {
+			result += string(content[i])
+			i++
+			continue
+		}
+
+		// Check if we're at the start of a potential pattern
+		// Pattern should start with a letter or underscore
+		if (content[i] >= 'a' && content[i] <= 'z') ||
+		   (content[i] >= 'A' && content[i] <= 'Z') ||
+		   content[i] == '_' {
+
+			// Look ahead to see if this contains the technical pattern markers
+			start := i
+			hasUnderscore := false
+			hasBraces := false
+			hasComma := false
+
+			// Scan ahead to find the end of this potential pattern
+			end := i
+			for end < len(content) {
+				ch := content[end]
+
+				// Pattern continues with alphanumeric, underscore, braces, comma
+				if (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+				   (ch >= '0' && ch <= '9') || ch == '_' ||
+				   ch == '{' || ch == '}' || ch == ',' {
+
+					if ch == '_' {
+						hasUnderscore = true
+					}
+					if ch == '{' || ch == '}' {
+						hasBraces = true
+					}
+					if ch == ',' {
+						hasComma = true
+					}
+					end++
+				} else {
+					break
+				}
+			}
+
+			// If we found a pattern with underscores, braces, and commas, wrap it
+			if end > start && hasUnderscore && hasBraces && hasComma {
+				pattern := content[start:end]
+				// Make sure it's not already wrapped in backticks
+				if start == 0 || content[start-1] != '`' {
+					result += "`" + pattern + "`"
+					i = end
+					continue
+				}
+			}
+		}
+
+		result += string(content[i])
+		i++
+	}
+
+	return result
+}
+
 // cleanLinkText removes [] prefix from link text and moves it to href
 func cleanLinkText(line string) string {
 	result := ""
@@ -700,9 +804,30 @@ func main() {
 
 	fmt.Printf("Converting docs from %s to %s\n", srcDir, dstDir)
 
-	// Remove and recreate destination directory
-	os.RemoveAll(dstDir)
-	os.MkdirAll(dstDir, 0755)
+	// Files to preserve during conversion (don't delete these)
+	preserveFiles := map[string]bool{
+		"overview.mdx": true,
+	}
+
+	// Instead of removing entire directory, selectively remove only generated files
+	// This preserves manually created files like overview.mdx
+	if _, err := os.Stat(dstDir); err == nil {
+		// Directory exists, remove only .mdx files that aren't in preserve list
+		filepath.Walk(dstDir, func(path string, info os.FileInfo, err error) error {
+			if err != nil || info.IsDir() {
+				return nil
+			}
+
+			filename := filepath.Base(path)
+			if !preserveFiles[filename] && strings.HasSuffix(path, ".mdx") {
+				os.Remove(path)
+			}
+			return nil
+		})
+	} else {
+		// Directory doesn't exist, create it
+		os.MkdirAll(dstDir, 0755)
+	}
 
 	// Walk through source directory
 	err = filepath.Walk(srcDir, func(path string, info os.FileInfo, err error) error {

public/talos/v1.12/reference/configuration/block/existingvolumeconfig.mdx

@@ -147,10 +147,3 @@ MountSpec describes how the volume is mounted.
     </tr>
   </tbody>
 </table>
-
-
-
-
-
-
-

public/talos/v1.12/reference/configuration/block/rawvolumeconfig.mdx

@@ -448,16 +448,3 @@ EncryptionKeyTPMOptions represents the options for TPM-based key protection.
     </tr>
   </tbody>
 </table>
-
-
-
-
-
-
-
-
-
-
-
-
-

public/talos/v1.12/reference/configuration/block/swapvolumeconfig.mdx

@@ -446,16 +446,3 @@ EncryptionKeyTPMOptions represents the options for TPM-based key protection.
     </tr>
   </tbody>
 </table>
-
-
-
-
-
-
-
-
-
-
-
-
-

public/talos/v1.12/reference/configuration/block/uservolumeconfig.mdx

@@ -591,16 +591,3 @@ EncryptionKeyTPMOptions represents the options for TPM-based key protection.
     </tr>
   </tbody>
 </table>
-
-
-
-
-
-
-
-
-
-
-
-
-

public/talos/v1.12/reference/configuration/block/volumeconfig.mdx

@@ -448,16 +448,3 @@ EncryptionKeyTPMOptions represents the options for TPM-based key protection.
     </tr>
   </tbody>
 </table>
-
-
-
-
-
-
-
-
-
-
-
-
-

public/talos/v1.12/reference/configuration/block/zswapconfig.mdx

@@ -49,8 +49,3 @@ shrinkerEnabled: true # Enable the shrinker feature: kernel might move
     </tr>
   </tbody>
 </table>
-
-
-
-
-

public/talos/v1.12/reference/configuration/cli.mdx

@@ -253,7 +253,7 @@ talosctl cluster create docker [flags]
       --config-patch-workers stringArray         patch generated machineconfigs (applied to 'worker' type)
       --cpus-controlplanes string                the share of CPUs as fraction for each control plane/VM (default "2.0")
       --cpus-workers string                      the share of CPUs as fraction for each worker/VM (default "2.0")
-  -p, --exposed-ports string                     comma-separated list of ports/protocols to expose on init node. Ex -p {"<"}hostPort{">"}:{"<"}containerPort{">"}/<protocol (tcp or udp)>
+  -p, --exposed-ports string                     comma-separated list of ports/protocols to expose on init node. Ex -p {"<"}hostPort{">"}:{"<"}containerPort{">"}/{"<"}protocol (tcp or udp){">"}
   -h, --help                                     help for docker
       --host-ip string                           Host IP to forward exposed ports to (default "0.0.0.0")
       --image string                             the talos image to run (default "ghcr.io/siderolabs/talos:v1.12.0-beta.1")
@@ -649,7 +649,7 @@ talosctl config merge {"<"}from{">"} [flags]
 Generate a new client configuration file
 
 ```
-talosctl config new [<path>] [flags]
+talosctl config new [{"<"}path{">"}] [flags]
 ```
 
 ### Options
@@ -1340,7 +1340,7 @@ talosctl etcd remove-member {"<"}member ID{">"} [flags]
 Stream snapshot of the etcd node to the path.
 
 ```
-talosctl etcd snapshot <path> [flags]
+talosctl etcd snapshot {"<"}path{">"} [flags]
 ```
 
 ### Options
@@ -2692,7 +2692,7 @@ talosctl processes [flags]
 Read a file on the machine
 
 ```
-talosctl read <path> [flags]
+talosctl read {"<"}path{">"} [flags]
 ```
 
 ### Options
@@ -3289,4 +3289,3 @@ A CLI for out-of-band management of Kubernetes nodes created by Talos
 * [talosctl validate](#talosctl-validate)	 - Validate config
 * [talosctl version](#talosctl-version)	 - Prints the version
 * [talosctl wipe](#talosctl-wipe)	 - Wipe block device or volumes
-

public/talos/v1.12/reference/configuration/cri/registryauthconfig.mdx

@@ -68,8 +68,3 @@ password: my-password # Username/password authentication.
     </tr>
   </tbody>
 </table>
-
-
-
-
-

public/talos/v1.12/reference/configuration/cri/registrymirrorconfig.mdx

@@ -94,10 +94,3 @@ RegistryEndpoint defines a registry mirror endpoint.
     </tr>
   </tbody>
 </table>
-
-
-
-
-
-
-