Support custom comment patterns (e.g., MDX)

[ptgott]

Check for existing issues

• Completed

Describe the feature

Vale version: v3.0.6 (at 55f450fe90d954b9c2019c36560472603e925cc3)

Summary

When using Vale with MDX files, I've mostly found success by setting mdx = md in the [formats] field of .vale.ini. One incompatibility between MDX and MD will make it difficult to implement Vale in my organization, though: the fact that Vale ignores MDX comments, which use {/* This syntax */}. Since Vale enables you to temporarily switch a rule on and off using comments, ignoring MDX comments means that docs authors can't configure Vale to ignore specific document elements. This will make it cumbersome for docs authors who run into edge cases.

Testing

Let's say we want to lint this MDX document:

 # Hello

This is a paragraph.

{/* SHOULD BE A COMMENT */}

End of doc.

The .vale.ini file includes this setting:

[formats]
mdx = md

I ran vale with dlv to lint the example file and set a breakpoint when we use Goldmark to convert the Markdown doc to HTML:

vale/internal/lint/md.go

Lines 41 to 43 in 55f450f

	if err = goldMd.Convert([]byte(s), &buf); err != nil {
	return core.NewE100(f.Path, err)
	}

After this, the resulting HTML fragment looks like this:

"<h1>Hello</h1>\n<p>This is a paragraph.</p>\n<p>{/* SHOULD BE A COMMENT */}</p>\n<p>End of doc.</p>\n"

The MDX comment is in an HTML paragraph tag.

Possible solution

Since MDX does not allow for standard Markdown comments (<!-- -->), supporting MDX requires allowing custom comment delimiters.

We could add a config field called CommentPattern or similar that takes a regular expression. In lintMarkdown, before applying the Goldmark conversion, we could replace instances of the CommentPattern regex with a standard HTML comment tag. When we apply the conversion, comments would be parsed as expected.

I'm happy to take this on if you don't have the bandwidth. Thanks!

[jdkato]

I'm happy to take this on if you don't have the bandwidth. Thanks!

👍

[ankargren]

Hey! My team has the exact same issue, so I just want to express my deepest encouragement on fixing this. I've managed to turn Vale completely on and off by doing:

{/*
<!-- vale off -->
*/}

the text goes here

{/*
<!-- vale on -->
*/}

but have never succeeded getting it to work using say

{/*
<!-- vale Google.We = NO -->
*/}

We rock!

{/*
<!-- vale Google.We = YES -->
*/}

[discdiver]

+1