Add support for controlling the indentation of Markdown headers (#120)

cmd/root.go

@@ -37,6 +37,7 @@ func init() {
 
 	markdownCmd.PersistentFlags().BoolVar(new(bool), "no-required", false, "omit \"Required\" column when generating Markdown")
 	markdownCmd.PersistentFlags().BoolVar(new(bool), "no-escape", false, "do not escape special characters")
+	markdownCmd.PersistentFlags().IntVar(&settings.MarkdownIndent, "indent", 2, "indention level of Markdown sections [1, 2, 3, 4, 5]")
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.

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

@@ -77,7 +77,7 @@ func printFencedCodeBlock(code string) string {
 
 func printInput(buffer *bytes.Buffer, input doc.Input, settings *settings.Settings) {
 	buffer.WriteString("\n")
-	buffer.WriteString(fmt.Sprintf("### %s\n\n", markdown.SanitizeName(input.Name, settings)))
+	buffer.WriteString(fmt.Sprintf("%s %s\n\n", markdown.GenerateIndentation(1, settings), 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))
 
@@ -89,7 +89,7 @@ func printInput(buffer *bytes.Buffer, input doc.Input, settings *settings.Settin
 
 func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Settings) {
 	if settings.ShowRequired {
-		buffer.WriteString("## Required Inputs\n\n")
+		buffer.WriteString(fmt.Sprintf("%s Required Inputs\n\n", markdown.GenerateIndentation(0, settings)))
 		buffer.WriteString("The following input variables are required:\n")
 
 		for _, input := range inputs {
@@ -99,7 +99,7 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Se
 		}
 
 		buffer.WriteString("\n")
-		buffer.WriteString("## Optional Inputs\n\n")
+		buffer.WriteString(fmt.Sprintf("%s Optional Inputs\n\n", markdown.GenerateIndentation(0, settings)))
 		buffer.WriteString("The following input variables are optional (have default values):\n")
 
 		for _, input := range inputs {
@@ -108,7 +108,7 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Se
 			}
 		}
 	} else {
-		buffer.WriteString("## Inputs\n\n")
+		buffer.WriteString(fmt.Sprintf("%s Inputs\n\n", markdown.GenerateIndentation(0, settings)))
 		buffer.WriteString("The following input variables are supported:\n")
 
 		for _, input := range inputs {
@@ -118,12 +118,12 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Se
 }
 
 func printOutputs(buffer *bytes.Buffer, outputs []doc.Output, settings *settings.Settings) {
-	buffer.WriteString("## Outputs\n\n")
+	buffer.WriteString(fmt.Sprintf("%s Outputs\n\n", markdown.GenerateIndentation(0, settings)))
 	buffer.WriteString("The following outputs are exported:\n")
 
 	for _, output := range outputs {
 		buffer.WriteString("\n")
-		buffer.WriteString(fmt.Sprintf("### %s\n\n", markdown.SanitizeName(output.Name, settings)))
+		buffer.WriteString(fmt.Sprintf("%s %s\n\n", markdown.GenerateIndentation(1, settings), 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

@@ -128,3 +128,63 @@ func TestPrintWithEscapeName(t *testing.T) {
 
 	assert.Equal(t, expected, actual)
 }
+
+func TestPrintWithIndentationBellowAllowed(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = &_settings.Settings{
+		MarkdownIndent: 0,
+	}
+
+	actual, err := document.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("document-WithIndentationBellowAllowed")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}
+
+func TestPrintWithIndentationAboveAllowed(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = &_settings.Settings{
+		MarkdownIndent: 10,
+	}
+
+	actual, err := document.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("document-WithIndentationAboveAllowed")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}
+
+func TestPrintWithIndentationOfFour(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = &_settings.Settings{
+		MarkdownIndent: 4,
+	}
+
+	actual, err := document.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("document-WithIndentationOfFour")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}

internal/pkg/print/markdown/document/testdata/document-WithIndentationAboveAllowed.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-WithIndentationBellowAllowed.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-WithIndentationOfFour.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/markdown.go

@@ -80,3 +80,19 @@ func Sanitize(markdown string) string {
 
 	return result
 }
+
+// GenerateIndentation generates indentation of Markdown headers
+// with base level of provided 'settings.MarkdownIndent' plus any
+// extra level needed for subsection (e.g. 'Required Inputs' which
+// is a subsection of 'Inputs' section)
+func GenerateIndentation(extra int, settings *settings.Settings) string {
+	var base = settings.MarkdownIndent
+	if base < 1 || base > 5 {
+		base = 2
+	}
+	var indent string
+	for i := 0; i < base+extra; i++ {
+		indent += "#"
+	}
+	return indent
+}

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

@@ -60,7 +60,7 @@ func printComment(buffer *bytes.Buffer, comment string, settings *settings.Setti
 }
 
 func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Settings) {
-	buffer.WriteString("## Inputs\n\n")
+	buffer.WriteString(fmt.Sprintf("%s Inputs\n\n", markdown.GenerateIndentation(0, settings)))
 	buffer.WriteString("| Name | Description | Type | Default |")
 
 	if settings.ShowRequired {
@@ -102,7 +102,7 @@ func printIsInputRequired(input *doc.Input) string {
 }
 
 func printOutputs(buffer *bytes.Buffer, outputs []doc.Output, settings *settings.Settings) {
-	buffer.WriteString("## Outputs\n\n")
+	buffer.WriteString(fmt.Sprintf("%s Outputs\n\n", markdown.GenerateIndentation(0, settings)))
 	buffer.WriteString("| Name | Description |\n")
 	buffer.WriteString("|------|-------------|\n")
 

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

@@ -128,3 +128,63 @@ func TestPrintWithEscapeName(t *testing.T) {
 
 	assert.Equal(t, expected, actual)
 }
+
+func TestPrintWithIndentationBellowAllowed(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = &_settings.Settings{
+		MarkdownIndent: 0,
+	}
+
+	actual, err := table.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("table-WithIndentationBellowAllowed")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}
+
+func TestPrintWithIndentationAboveAllowed(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = &_settings.Settings{
+		MarkdownIndent: 10,
+	}
+
+	actual, err := table.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("table-WithIndentationAboveAllowed")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}
+
+func TestPrintWithIndentationOfFour(t *testing.T) {
+	doc := doc.TestDoc(t, "../..")
+
+	var settings = &_settings.Settings{
+		MarkdownIndent: 4,
+	}
+
+	actual, err := table.Print(doc, settings)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expected, err := print.ReadGoldenFile("table-WithIndentationOfFour")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, expected, actual)
+}

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

@@ -0,0 +1,41 @@
+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
+
+| Name | Description | Type | Default |
+|------|-------------|:----:|:-----:|
+| unquoted |  | string | n/a |
+| string-3 |  | string | `""` |
+| string-2 | It's string number two. | string | n/a |
+| string-1 | It's string number one. | string | `"bar"` |
+| map-3 |  | map | `<map>` |
+| map-2 | It's map number two. | map | n/a |
+| map-1 | It's map number one. | map | `<map>` |
+| list-3 |  | list | `<list>` |
+| list-2 | It's list number two. | list | n/a |
+| list-1 | It's list number one. | list | `<list>` |
+| input_with_underscores | A variable with underscores. | string | n/a |
+| input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| unquoted | It's unquoted output. |
+| output-2 | It's output number two. |
+| output-1 | It's output number one. |

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

@@ -0,0 +1,41 @@
+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
+
+| Name | Description | Type | Default |
+|------|-------------|:----:|:-----:|
+| unquoted |  | string | n/a |
+| string-3 |  | string | `""` |
+| string-2 | It's string number two. | string | n/a |
+| string-1 | It's string number one. | string | `"bar"` |
+| map-3 |  | map | `<map>` |
+| map-2 | It's map number two. | map | n/a |
+| map-1 | It's map number one. | map | `<map>` |
+| list-3 |  | list | `<list>` |
+| list-2 | It's list number two. | list | n/a |
+| list-1 | It's list number one. | list | `<list>` |
+| input_with_underscores | A variable with underscores. | string | n/a |
+| input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| unquoted | It's unquoted output. |
+| output-2 | It's output number two. |
+| output-1 | It's output number one. |

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

@@ -0,0 +1,41 @@
+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
+
+| Name | Description | Type | Default |
+|------|-------------|:----:|:-----:|
+| unquoted |  | string | n/a |
+| string-3 |  | string | `""` |
+| string-2 | It's string number two. | string | n/a |
+| string-1 | It's string number one. | string | `"bar"` |
+| map-3 |  | map | `<map>` |
+| map-2 | It's map number two. | map | n/a |
+| map-1 | It's map number one. | map | `<map>` |
+| list-3 |  | list | `<list>` |
+| list-2 | It's list number two. | list | n/a |
+| list-1 | It's list number one. | list | `<list>` |
+| input_with_underscores | A variable with underscores. | string | n/a |
+| input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` |
+
+#### Outputs
+
+| Name | Description |
+|------|-------------|
+| unquoted | It's unquoted output. |
+| output-2 | It's output number two. |
+| output-1 | It's output number one. |

internal/pkg/settings/settings.go

@@ -10,6 +10,10 @@ type Settings struct {
 	// scope: Markdown
 	EscapeMarkdown bool
 
+	// MarkdownIndent control the indentation of Markdown headers [available: 1, 2, 3, 4, 5] (default: 2)
+	// scope: Markdown
+	MarkdownIndent int
+
 	// ShowRequired show "Required" column when generating Markdown (default: true)
 	// scope: Markdown
 	ShowRequired bool
@@ -28,6 +32,7 @@ func NewSettings() *Settings {
 	return &Settings{
 		AggregateTypeDefaults: false,
 		EscapeMarkdown:        true,
+		MarkdownIndent:        2,
 		ShowRequired:          true,
 		SortByName:            true,
 		SortInputsByRequired:  false,