fix: Prevent Manually Added Content in CLI Docs to be Overwritten

docs/pages/project/contributing/contributing-cli.md

@@ -201,6 +201,10 @@ Though the command page is generated automatically by the Cobra CLI library, the
 - [cmds.yml](https://github.com/meshery/meshery/blob/master/docs/_data/mesheryctlcommands/cmds.yml) - The YAML file containing the data about the commands
 - [mesheryctl-commands.md](https://github.com/meshery/meshery/blob/master/docs/pages/reference/mesheryctl-commands.md) - The markdown page of the command reference documentation
 
+## Preserving Manually Added Documentation with Cobra CLI
+
+We use Cobra CLI and GitHub Actions to automate the generation of command documentation. To protect any manually added content and ensure it remains intact after regeneration, follow this format: {% raw %}{% include folder-name/file-name %}{% endraw %}. This format should reference an external file where your manual changes are stored. Any content added using this format will not be altered during the documentation generation process. When making new changes or additions, be sure to place them at the end of the documentation to keep it organized and consistent.
+
 ### References
 
 - [jarcoal/httpmock](https://github.com/jarcoal/httpmock)

mesheryctl/doc/doc.go

@@ -22,6 +22,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"time"
 
@@ -133,7 +134,7 @@ func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error {
 }
 
 // GenMarkdownCustom creates custom markdown output.
-func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error {
+func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, manuallyAddedContent map[int]string) error {
 	// InitDefaultHelpCmd add the help command to the command tree.
 	cmd.InitDefaultHelpCmd()
 	// InitDefaultHelpFlag add the help flag to the command tree.
@@ -176,6 +177,7 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error {
 					buf.WriteString(strings.Replace(examples[i], "// ", "", -1) + "\n")
 				} else {
 					// Code Block Line
+
 					buf.WriteString(fmt.Sprintf("<pre class='codeblock-pre'>\n<div class='codeblock'>\n%s\n\n</div>\n</pre> \n\n", examples[i]))
 				}
 			}
@@ -197,6 +199,13 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error {
 		buf.WriteString("\n\n")
 	}
 
+	if len(manuallyAddedContent) > 0 {
+		for _, content := range manuallyAddedContent {
+			buf.WriteString("\n")
+			buf.WriteString("{% include " + content + " %}" + "\n")
+		}
+	}
+
 	if hasSeeAlso(cmd) {
 		buf.WriteString("## See Also\n\n")
 		if cmd.HasParent() {
@@ -206,9 +215,10 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error {
 				}
 			})
 		}
-		buf.WriteString("Go back to [command reference index](/reference/mesheryctl/) ")
+		buf.WriteString("Go back to [command reference index](/reference/mesheryctl/), if you want to add content manually to the CLI documentation, please refer to the [instruction](/project/contributing/contributing-cli#preserving-manually-added-documentation-with-cobra-cli) for guidance.")
 		buf.WriteString("\n")
 	}
+
 	if !cmd.DisableAutoGenTag {
 		buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n")
 	}
@@ -243,6 +253,9 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
 
 	basename := strings.Replace(cmd.CommandPath(), " ", "-", -1) + ".md"
 	filename := filepath.Join(dir, basename)
+
+	manuallyAddedContent, _ := getManuallyAddedContentMap(filename)
+
 	f, err := os.Create(filename)
 	if err != nil {
 		return err
@@ -254,13 +267,37 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
 		return err
 	}
 
-	err = GenMarkdownCustom(cmd, f)
+	err = GenMarkdownCustom(cmd, f, manuallyAddedContent)
 	if err != nil {
 		return err
 	}
 	return nil
 }
 
+func getManuallyAddedContentMap(filename string) (map[int]string, error) {
+	manuallyAddedContentMap := make(map[int]string)
+
+	_, err := os.Stat(filename)
+	if err != nil {
+		return manuallyAddedContentMap, err
+	}
+
+	existingContent, err := os.ReadFile(filename)
+	if err != nil {
+		return manuallyAddedContentMap, err
+	}
+
+	content := string(existingContent)
+
+	includePattern := regexp.MustCompile(`\{\%\s*include\s+([^%]+)\s+\%\}`)
+	includeMatches := includePattern.FindAllStringSubmatch(content, -1)
+	for i, match := range includeMatches {
+		// Store the include content in the map with order as the key
+		manuallyAddedContentMap[i] = strings.TrimSpace(match[1])
+	}
+	return manuallyAddedContentMap, nil
+}
+
 // GenYamlTreeCustom creates custom yaml output.
 func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
 	for _, c := range cmd.Commands() {

mesheryctl/doc/doc_test.go

@@ -79,11 +79,12 @@ var _ = Describe("Tests for Doc", func() {
 
 			// add Example for cmd for test
 			cmd.Example = "test_example"
+			manuallyAddedContent, _ := getManuallyAddedContentMap("test.md")
 
 			// io.Writer
 			buf := &bytes.Buffer{}
 			// call GenMarkdownCustom
-			err := GenMarkdownCustom(cmd, buf)
+			err := GenMarkdownCustom(cmd, buf, manuallyAddedContent)
 			// check if err is nil
 			Expect(err).To(BeNil())
 			// check if buf is not empty
@@ -121,6 +122,18 @@ var _ = Describe("Tests for Doc", func() {
 		})
 	})
 
+	//Test getManuallyAddedContentMap
+	Context("Test getManuallyAddedContentMap function", func() {
+		It("should return nil", func() {
+
+			// call getManuallyAddedContentMap
+			_, err := getManuallyAddedContentMap("test.md")
+
+			// check if err is nil
+			Expect(err).To(BeNil())
+		})
+	})
+
 	//TestGenYamlCustom is the test for GenYamlCustom function
 	Context("Test GenYamlCustom function", func() {
 		It("should return specific sub-strings", func() {