Merge pull request #4126 from afbjorklund/escape-markdown

Escape text in the command markdown documentation

Author: AkihiroSuda

cmd/limactl/copy.go

@@ -32,7 +32,10 @@ Backends:
   rsync  - Uses rsync for faster transfers with resume capability (requires rsync on both host and guest)
   scp    - Uses scp for reliable transfers (always available)
 
-Examples:
+Not to be confused with 'limactl clone'.
+`
+
+const copyExample = `
   # Copy file from guest to host (auto backend)
   limactl copy default:/etc/os-release .
 
@@ -47,8 +50,6 @@ Examples:
 
   # Copy multiple files
   limactl copy file1.txt file2.txt default:/tmp/
-
-Not to be confused with 'limactl clone'.
 `
 
 type copyTool string
@@ -72,6 +73,7 @@ func newCopyCommand() *cobra.Command {
 		Aliases: []string{"cp"},
 		Short:   "Copy files between host and guest",
 		Long:    copyHelp,
+		Example: copyExample,
 		Args:    WrapArgsError(cobra.MinimumNArgs(2)),
 		RunE:    copyAction,
 		GroupID: advancedCommand,

cmd/limactl/gendoc.go

@@ -101,7 +101,26 @@ and $LIMA_WORKDIR.
 	return doc.GenManTree(cmd.Root(), header, dir)
 }
 
+func escapeMarkdown(text string) string {
+	lines := strings.Split(text, "\n")
+	for i := range lines {
+		// Need to escape backticks first, before adding more
+		for _, c := range strings.Split("\\`*_[]()#+-.|", "") {
+			lines[i] = strings.ReplaceAll(lines[i], c, "\\"+c)
+		}
+		if i < len(lines)-1 {
+			if lines[i] != "" && lines[i+1] != "" {
+				lines[i] += "  " // line break
+			}
+		}
+	}
+	return strings.Join(lines, "\n")
+}
+
 func genDocsy(cmd *cobra.Command, dir string) error {
+	for _, c := range cmd.Root().Commands() {
+		c.Long = escapeMarkdown(c.Long)
+	}
 	return doc.GenMarkdownTreeCustom(cmd.Root(), dir, func(s string) string {
 		// Replace limactl_completion_bash to completion bash for docsy title
 		name := filepath.Base(s)