search

errata-ai / vale

:pencil: A markup-aware linter for prose built with speed and extensibility in mind.
https://vale.sh
MIT License
4.3k stars 144 forks source link

Can't use ignore with `raw` scope. #194

Closed Ravlen closed 4 years ago

Ravlen commented 4 years ago

@jdkato We have joyfully made use of the raw scope in the GitLab documentation project, you can see some of our rules here: https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab. We love it!

Unfortunately, we have run into a small problem for the next batch of rules we are working on. We want to make use of the ignore function (https://errata-ai.github.io/vale/config/#ignoring-parts-of-your-documents), but this does not work with the raw scope.

Is it possible to make the raw scope watch for <!-- vale off -->?

I also tested with custom block ignores, and it doesn't seem to pick it up either. The custom ignore works with a regular scope, and doesn't work with a raw scope.

jdkato commented 4 years ago

One thing that makes Vale unique from every other prose linter that I'm aware of is the fact that it doesn't operate on the actual contents of a file: it sees every one of its supported formats (Markdown, AsciiDoc, reStructuredText, and XML) as HTML. This is a powerful feature because it allows Vale to treat all of its supported formats the same while still offering a rich understanding of their syntaxes. For example, you can create a style that enforces a certain heading style (a rule that would typically be syntax-specific -- e.g., # in Markdown) and it'll work across every supported format.

scope: raw, on the other hand, throws all of this away: it simply uses the "raw" file contents, which means that scopes (headings, links, inline code, etc.) are now all format-dependent. This results in styles that will only work for one format. In other words, scope: raw instructs Vale to skip the markup processing that the HTML-related features (comments, block ignores, etc.) require -- essentially making them incompatible ideas.

Ultimately, as I've said in related issues, I think Vale is very good at what it's designed to do: lint prose of varying formats. It simply isn't designed to lint markup, though, which appears to be the reason you're using scope: raw.

And while markup-linting may be something I explore in the future, remark-lint would probably fit your markup-linting needs better right now: it includes many similar features to Vale (custom rules, preset styles, etc.), but is specifically designed for Markdown syntax (instead of prose).