From 34df92d5fb6011d806bd01b512f3d08b3737f123 Mon Sep 17 00:00:00 2001
From: Kian Parvin <kian.parvin@canonical.com>
Date: Tue, 3 Dec 2024 15:07:44 +0200
Subject: [PATCH 1/2] feat: allow markdown escaping to be skipped

---
 documentation.go | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/documentation.go b/documentation.go
index 326c0d04..48315821 100644
--- a/documentation.go
+++ b/documentation.go
@@ -51,12 +51,13 @@ in the file above.
 
 type documentationCommand struct {
 	CommandBase
-	super   *SuperCommand
-	out     string
-	noIndex bool
-	split   bool
-	url     string
-	idsPath string
+	super          *SuperCommand
+	out            string
+	noIndex        bool
+	split          bool
+	escapeMarkdown bool
+	url            string
+	idsPath        string
 	// ids is contains a numeric id of every command
 	// add-cloud: 1112
 	// remove-user: 3333
@@ -87,6 +88,7 @@ func (c *documentationCommand) SetFlags(f *gnuflag.FlagSet) {
 	f.StringVar(&c.out, "out", "", "Documentation output folder if not set the result is displayed using the standard output")
 	f.BoolVar(&c.noIndex, "no-index", false, "Do not generate the commands index")
 	f.BoolVar(&c.split, "split", false, "Generate a separate Markdown file for each command")
+	f.BoolVar(&c.split, "escape-markdown", true, "Escape special markdown characters e.g. < > |")
 	f.StringVar(&c.url, "url", "", "Documentation host URL")
 	f.StringVar(&c.idsPath, "discourse-ids", "", "File containing a mapping of commands and their discourse ids")
 }
@@ -422,7 +424,10 @@ func (c *documentationCommand) formatCommand(ref commandReference, title bool, c
 	}
 
 	// Details
-	doc := EscapeMarkdown(info.Doc)
+	doc := info.Doc
+	if c.escapeMarkdown {
+		doc = EscapeMarkdown(doc)
+	}
 	if strings.TrimSpace(doc) != "" {
 		formatted += "## Details\n" + doc + "\n\n"
 	}

From 4e91dc5921dfbafdae0671f19ab4fb647650c0ca Mon Sep 17 00:00:00 2001
From: Kian Parvin <kian.parvin@canonical.com>
Date: Tue, 3 Dec 2024 15:09:06 +0200
Subject: [PATCH 2/2] chore: fix subcommand URI fragments

Links to a different section of text in markdown should use - instead of _ for links with spaces.
Also adds a newline before the line break marker in the index.
---
 documentation.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation.go b/documentation.go
index 48315821..f4eb6db4 100644
--- a/documentation.go
+++ b/documentation.go
@@ -329,7 +329,7 @@ func (c *documentationCommand) writeIndex(w io.Writer) error {
 		}
 		// TODO: handle subcommands ??
 	}
-	_, err = fmt.Fprintf(w, "---\n\n")
+	_, err = fmt.Fprintf(w, "\n---\n\n")
 	return err
 }
 
@@ -628,7 +628,7 @@ func (c *documentationCommand) formatSubcommands(subcommands map[string]string,
 		output += "## Subcommands\n"
 		for _, name := range sorted {
 			output += fmt.Sprintf("- [%s](%s)\n", name,
-				c.linkForCommand(strings.Join(append(commandSeq[1:], name), "_")))
+				c.linkForCommand(strings.Join(append(commandSeq[1:], name), "-")))
 		}
 		output += "\n"
 	}