Add --no-escape flag for Markdown printer

cmd/root.go

@@ -20,9 +20,11 @@ var rootCmd = &cobra.Command{
 	PersistentPreRun: func(cmd *cobra.Command, args []string) {
 		nosort, _ := cmd.Flags().GetBool("no-sort")
 		norequired, _ := cmd.Flags().GetBool("no-required")
+		noescape, _ := cmd.Flags().GetBool("no-escape")
 
 		settings.SortByName = !nosort
 		settings.ShowRequired = !norequired
+		settings.EscapeMarkdown = !noescape
 	},
 }
 
@@ -36,7 +38,10 @@ func init() {
 	rootCmd.PersistentFlags().BoolVar(&settings.AggregateTypeDefaults, "with-aggregate-type-defaults", false, "print default values of aggregate types")
 
 	var norequired bool
+	var noesape bool
+
 	markdownCmd.PersistentFlags().BoolVar(&norequired, "no-required", false, "omit \"Required\" column when generating Markdown")
+	markdownCmd.PersistentFlags().BoolVar(&noesape, "no-escape", false, "do not escape special characters")
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.

internal/pkg/print/markdown/document/document.go

@@ -3,7 +3,6 @@ package document
 import (
 	"bytes"
 	"fmt"
-	"strings"
 
 	"github.com/segmentio/terraform-docs/internal/pkg/doc"
 	"github.com/segmentio/terraform-docs/internal/pkg/print"
@@ -66,18 +65,20 @@ func printComment(buffer *bytes.Buffer, comment string, settings settings.Settin
 
 func printFencedCodeBlock(code string) string {
 	var buffer bytes.Buffer
+
 	buffer.WriteString("\n\n")
 	buffer.WriteString("```json\n")
 	buffer.WriteString(code)
 	buffer.WriteString("\n")
 	buffer.WriteString("```")
+
 	return buffer.String()
 }
 
 func printInput(buffer *bytes.Buffer, input doc.Input, settings settings.Settings) {
 	buffer.WriteString("\n")
-	buffer.WriteString(fmt.Sprintf("### %s\n\n", strings.Replace(input.Name, "_", "\\_", -1)))
-	buffer.WriteString(fmt.Sprintf("Description: %s\n\n", markdown.SanitizeDescription(input.Description)))
+	buffer.WriteString(fmt.Sprintf("### %s\n\n", markdown.SanitizeName(input.Name, settings)))
+	buffer.WriteString(fmt.Sprintf("Description: %s\n\n", markdown.SanitizeDescription(input.Description, settings)))
 	buffer.WriteString(fmt.Sprintf("Type: `%s`\n", input.Type))
 
 	// Don't print defaults for required inputs when we're already explicit about it being required
@@ -122,7 +123,7 @@ func printOutputs(buffer *bytes.Buffer, outputs []doc.Output, settings settings.
 
 	for _, output := range outputs {
 		buffer.WriteString("\n")
-		buffer.WriteString(fmt.Sprintf("### %s\n\n", strings.Replace(output.Name, "_", "\\_", -1)))
-		buffer.WriteString(fmt.Sprintf("Description: %s\n", markdown.SanitizeDescription(output.Description)))
+		buffer.WriteString(fmt.Sprintf("### %s\n\n", markdown.SanitizeName(output.Name, settings)))
+		buffer.WriteString(fmt.Sprintf("Description: %s\n", markdown.SanitizeDescription(output.Description, settings)))
 	}
 }

internal/pkg/print/markdown/document/document_test.go

@@ -108,3 +108,23 @@ func TestPrintWithSortInputsByRequired(t *testing.T) {
 
 	assert.Equal(t, expected, actual)
 }
+
+func TestPrintWithEscapeName(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = _settings.Settings{
+		EscapeMarkdown: true,
+	}
+
+	actual, err := document.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("document-WithEscapeName")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}

internal/pkg/print/markdown/document/testdata/document-WithAggregateTypeDefaults.golden

@@ -123,7 +123,7 @@ Default:
 ]
 ```
 
-### input\_with\_underscores
+### input_with_underscores
 
 Description: A variable with underscores.
 

internal/pkg/print/markdown/document/testdata/document-WithEscapeName.golden

@@ -0,0 +1,132 @@
+Usage:
+
+module "foo" {
+  source = "github.com/foo/bar"
+
+  id   = "1234567890"
+  name = "baz"
+
+  zones = ["us-east-1", "us-west-1"]
+
+  tags = {
+    Name         = "baz"
+    Created-By   = "first.last@email.com"
+    Date-Created = "20180101"
+  }
+}
+
+## Inputs
+
+The following input variables are supported:
+
+### unquoted
+
+Description:
+
+Type: `string`
+
+Default: n/a
+
+### string-3
+
+Description:
+
+Type: `string`
+
+Default: `""`
+
+### string-2
+
+Description: It's string number two.
+
+Type: `string`
+
+Default: n/a
+
+### string-1
+
+Description: It's string number one.
+
+Type: `string`
+
+Default: `"bar"`
+
+### map-3
+
+Description:
+
+Type: `map`
+
+Default: `<map>`
+
+### map-2
+
+Description: It's map number two.
+
+Type: `map`
+
+Default: n/a
+
+### map-1
+
+Description: It's map number one.
+
+Type: `map`
+
+Default: `<map>`
+
+### list-3
+
+Description:
+
+Type: `list`
+
+Default: `<list>`
+
+### list-2
+
+Description: It's list number two.
+
+Type: `list`
+
+Default: n/a
+
+### list-1
+
+Description: It's list number one.
+
+Type: `list`
+
+Default: `<list>`
+
+### input\_with\_underscores
+
+Description: A variable with underscores.
+
+Type: `string`
+
+Default: n/a
+
+### input-with-pipe
+
+Description: It includes v1 \| v2 \| v3
+
+Type: `string`
+
+Default: `"v1"`
+
+## Outputs
+
+The following outputs are exported:
+
+### unquoted
+
+Description: It's unquoted output.
+
+### output-2
+
+Description: It's output number two.
+
+### output-1
+
+Description: It's output number one.

internal/pkg/print/markdown/document/testdata/document-WithRequired.golden

@@ -43,7 +43,7 @@ Description: It's list number two.
 
 Type: `list`
 
-### input\_with\_underscores
+### input_with_underscores
 
 Description: A variable with underscores.
 

internal/pkg/print/markdown/document/testdata/document-WithSortByName.golden

@@ -27,7 +27,7 @@ Type: `string`
 
 Default: `"v1"`
 
-### input\_with\_underscores
+### input_with_underscores
 
 Description: A variable with underscores.
 

internal/pkg/print/markdown/document/testdata/document-WithSortInputsByRequired.golden

@@ -19,7 +19,7 @@ module "foo" {
 
 The following input variables are supported:
 
-### input\_with\_underscores
+### input_with_underscores
 
 Description: A variable with underscores.
 

internal/pkg/print/markdown/document/testdata/document.golden

@@ -99,7 +99,7 @@ Type: `list`
 
 Default: `<list>`
 
-### input\_with\_underscores
+### input_with_underscores
 
 Description: A variable with underscores.
 

internal/pkg/print/markdown/markdown.go

@@ -3,12 +3,24 @@ package markdown
 import (
 	"regexp"
 	"strings"
+
+	"github.com/segmentio/terraform-docs/internal/pkg/settings"
 )
 
-// SanitizeDescription converts description to suitable Markdown representation. (including mline-break, illegal characters, etc)
-func SanitizeDescription(s string) string {
+// SanitizeName escapes underscore character which have special meaning in Markdown.
+func SanitizeName(s string, settings settings.Settings) string {
+	if settings.EscapeMarkdown {
+		// Escape underscore
+		s = strings.Replace(s, "_", "\\_", -1)
+	}
+
+	return s
+}
+
+// SanitizeDescription converts description to suitable Markdown representation. (including line-break, illegal characters, etc)
+func SanitizeDescription(s string, settings settings.Settings) string {
 	s = ConvertMultiLineText(s)
-	s = EscapeIllegalCharacters(s)
+	s = EscapeIllegalCharacters(s, settings)
 
 	return s
 }
@@ -27,12 +39,29 @@ func ConvertMultiLineText(s string) string {
 }
 
 // EscapeIllegalCharacters escapes characters which have special meaning in Markdown into their corresponding literal.
-func EscapeIllegalCharacters(s string) string {
+func EscapeIllegalCharacters(s string, settings settings.Settings) string {
 	// Escape pipe
 	s = strings.Replace(s, "|", "\\|", -1)
 
-	// Escape underscore
-	s = strings.Replace(s, "_", "\\_", -1)
+	if settings.EscapeMarkdown {
+		// Escape underscore
+		s = strings.Replace(s, "_", "\\_", -1)
+
+		// Escape asterisk
+		s = strings.Replace(s, "*", "\\*", -1)
+
+		// Escape paranthesis
+		s = strings.Replace(s, "(", "\\(", -1)
+		s = strings.Replace(s, ")", "\\)", -1)
+
+		// Escape brackets
+		s = strings.Replace(s, "[", "\\[", -1)
+		s = strings.Replace(s, "]", "\\]", -1)
+
+		// Escape curly brackets
+		s = strings.Replace(s, "{", "\\{", -1)
+		s = strings.Replace(s, "}", "\\}", -1)
+	}
 
 	return s
 }

internal/pkg/print/markdown/table/table.go

@@ -3,7 +3,6 @@ package table
 import (
 	"bytes"
 	"fmt"
-	"strings"
 
 	"github.com/segmentio/terraform-docs/internal/pkg/doc"
 	"github.com/segmentio/terraform-docs/internal/pkg/print"
@@ -81,8 +80,8 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings settings.Set
 	for _, input := range inputs {
 		buffer.WriteString(
 			fmt.Sprintf("| %s | %s | %s | %s |",
-				strings.Replace(input.Name, "_", "\\_", -1),
-				markdown.SanitizeDescription(input.Description),
+				markdown.SanitizeName(input.Name, settings),
+				markdown.SanitizeDescription(input.Description, settings),
 				input.Type,
 				getInputDefaultValue(&input, settings)))
 
@@ -110,7 +109,7 @@ func printOutputs(buffer *bytes.Buffer, outputs []doc.Output, settings settings.
 	for _, output := range outputs {
 		buffer.WriteString(
 			fmt.Sprintf("| %s | %s |\n",
-				strings.Replace(output.Name, "_", "\\_", -1),
-				markdown.SanitizeDescription(output.Description)))
+				markdown.SanitizeName(output.Name, settings),
+				markdown.SanitizeDescription(output.Description, settings)))
 	}
 }

internal/pkg/print/markdown/table/table_test.go

@@ -108,3 +108,23 @@ func TestPrintWithSortInputsByRequired(t *testing.T) {
 
 	assert.Equal(t, expected, actual)
 }
+
+func TestPrintWithEscapeName(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = _settings.Settings{
+		EscapeMarkdown: true,
+	}
+
+	actual, err := table.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("table-WithEscapeName")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}

internal/pkg/print/markdown/table/testdata/table-WithAggregateTypeDefaults.golden

@@ -29,7 +29,7 @@ module "foo" {
 | list-3 |  | list | `[]` |
 | list-2 | It's list number two. | list | n/a |
 | list-1 | It's list number one. | list | `[ "a", "b", "c" ]` |
-| input\_with\_underscores | A variable with underscores. | string | n/a |
+| input_with_underscores | A variable with underscores. | string | n/a |
 | input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` |
 
 ## Outputs