doc: Put description in separate section

The `Long` description was prepended to the Synopsis section which it
does not belong to - the synopsis should, by convention, only be the
syntax of the command and its options.

It's now added to a separate Description section.

Author: adombeck

doc/md_docs.go

@@ -63,15 +63,19 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 
 	buf.WriteString("## " + name + "\n\n")
 	buf.WriteString(cmd.Short + "\n\n")
-	if len(cmd.Long) > 0 {
-		buf.WriteString("### Synopsis\n\n")
-		buf.WriteString(cmd.Long + "\n\n")
-	}
 
 	if cmd.Runnable() {
+		if len(cmd.Long) > 0 {
+			buf.WriteString("### Synopsis\n\n")
+		}
 		fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.UseLine())
 	}
 
+	if len(cmd.Long) > 0 {
+		buf.WriteString("### Description\n\n")
+		buf.WriteString(cmd.Long + "\n\n")
+	}
+
 	if len(cmd.Example) > 0 {
 		buf.WriteString("### Examples\n\n")
 		fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.Example)