Support inline comments variation for Markdown and AsciiDoc

khos2ow · khos2ow · commit 0eea133cae0a · 2021-04-13T14:59:36.000-04:00
Some of the Markdown engines (e.g. Bitbucket Cloud) are not able to
process HTML comment but as a workaround they support variation of
inline comments as follow:

- `&lt;!-- This is a comment --&gt;`
- `[]: # (This is a comment)`
- `[]: # "This is a comment"`
- `[]: # 'This is a comment'`
- `[//]: # (This is a comment)`
- `[comment]: # (This is a comment)`

The following is also supported for AsciiDoc format:

- `// This is a comment`

Signed-off-by: Khosrow Moossavi &lt;khos2ow@gmail.com&gt;
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -197,6 +197,40 @@ output:
     {{ .Content }}
 ```
 
+### Template Comment
+
+Markdown doesn't officially support inline commenting, there are multiple ways
+to do it as a workaround, though. The following formats are supported as begin
+and end comments of a template:
+
+- `<!-- This is a comment -->`
+- `[]: # (This is a comment)`
+- `[]: # "This is a comment"`
+- `[]: # 'This is a comment'`
+- `[//]: # (This is a comment)`
+- `[comment]: # (This is a comment)`
+
+The following is also supported for AsciiDoc format:
+
+- `// This is a comment`
+
+The following can be used where HTML comments are not supported (e.g. Bitbucket
+Cloud):
+
+```yaml
+output:
+  file: README.md
+  mode: inject
+  template: |-
+    [//]: # (BEGIN_TF_DOCS)    
+    {{ .Content }}
+
+    [//]: # (END_TF_DOCS)
+```
+
+Note: The empty line before `[//]: # (END_TF_DOCS)` is mandatory in order for
+Markdown engine to properly process the comment line after the paragraph.
+
 ## Sort
 
 To enable sorting of elements `sort.enabled` (or `--sort bool` CLI flag) can be
diff --git a/internal/cli/config.go b/internal/cli/config.go
@@ -199,19 +199,45 @@ func (o *output) validate() error { //nolint:gocyclo
 			return fmt.Errorf("value of '--output-template' should contain at least 3 lines (begin comment, {{ .Content }}, and end comment)")
 		}
 
-		if !strings.Contains(lines[0], "<!--") || !strings.Contains(lines[0], "-->") {
+		if !isInlineComment(lines[0]) {
 			return fmt.Errorf("value of '--output-template' is missing begin comment")
 		}
 		o.BeginComment = strings.TrimSpace(lines[0])
 
-		if !strings.Contains(lines[len(lines)-1], "<!--") || !strings.Contains(lines[len(lines)-1], "-->") {
+		if !isInlineComment(lines[len(lines)-1]) {
 			return fmt.Errorf("value of '--output-template' is missing end comment")
 		}
 		o.EndComment = strings.TrimSpace(lines[len(lines)-1])
 	}
 	return nil
 }
 
+// Detect if a particular line is a Markdown comment
+//
+// ref: https://www.jamestharpe.com/markdown-comments/
+func isInlineComment(line string) bool {
+	switch {
+	// Markdown specific
+	case strings.HasPrefix(line, "<!--") && strings.HasSuffix(line, "-->"):
+		return true
+	case strings.HasPrefix(line, "[]: # ("):
+		return true
+	case strings.HasPrefix(line, "[]: # \""):
+		return true
+	case strings.HasPrefix(line, "[]: # '"):
+		return true
+	case strings.HasPrefix(line, "[//]: # ("):
+		return true
+	case strings.HasPrefix(line, "[comment]: # ("):
+		return true
+
+	// AsciiDoc specific
+	case strings.HasPrefix(line, "//"):
+		return true
+	}
+	return false
+}
+
 type outputvalues struct {
 	Enabled bool   `yaml:"enabled"`
 	From    string `yaml:"from"`
