centersl/terraform-docs
1
0
Fork 0
mirror of https://github.com/terraform-docs/terraform-docs.git synced 2026-03-27 12:58:35 +07:00
Code Issues Packages Projects Releases Wiki Activity

Support inline comments variation for Markdown and AsciiDoc

Browse Source 
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:

- `<!-- 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`

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This commit is contained in:
Khosrow Moossavi
2021-04-13 14:59:36 -04:00
parent 4031c661be
commit 0eea133cae
2 changed files with 62 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/user-guide/configuration.md
View File

@@ -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

30
internal/cli/config.go
View File

@@ -199,12 +199,12 @@ 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])
@@ -212,6 +212,32 @@ func (o *output) validate() error { //nolint:gocyclo
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"`