Override a Vale.Avoid error

[marians]

We have a vocabulary that has a reject.txt file containing the term k8s and K8s.

In a content paragraph, this phrase occurs:

- Some customers have been using [k8s-initiator-app](https://github.com/giantswarm/k8s-initiator-app/) to configure ...

The occurrence of k8s in k8s-initiator-app is highlighted by vale as an error:

Avoid using 'k8s'. Vale.Avoid

I would like to exclude the term k8s-initiator-app from this linting rule. How is that possible?

I tried adding the term k8s-initiator-app to accept.txt, but that didn't work. I also read something about an ignore.txt file, which this had no effect either.

[jdkato]

There are no exceptions for terms in reject.txt -- they are rejected as-is.

However, you have a few options:

1. Wrap k8s-initiator-app in a code span (as we're doing here):

- Some customers have been using [`k8s-initiator-app`](https://github.com/giantswarm/k8s-initiator-app/) to configure ...

2. Make the reject.txt entry more specific:

[kK]8s(?!-initiator-app)

[marians]

Thanks for the reply! Both options seem not really satisfactory to me. But I'll go with option two. Formatting Github repository links as a code literal is not what we aim for.

[jdkato]

If that's how you feel, I imagine one of us is misunderstanding something.

I'd argue that this is exactly what code spans are for: formatting non-prose tokens (as you've done in this very issue). But that's simply a matter of opinion.

The second option, quite literally, has the effect of excluding "the term k8s-initiator-app from the linting rule," while still flagging other instances of k8s. What is unsatisfactory about this?

There also is a third option: Instead of using reject.txt, you can write your own rule for finding instances of k8s. This may be more desirable if you have many cases that you want to exclude.

[marians]

Thanks a lot for the additional advice! I really appreciate it! And my apologies if my swift reply came across unkind. I'm grateful to have Vale as a tool helping us improve our documentation quality and consistency, which is really hard to do in an engineering team without any technical writers.

I will definitely at some point look into writing custom rules. For now, the [kK]8s(?!-initiator-app) way works just fine. If there are more exceptions to deal with, it might become more convenient to have a custom rule.

You are right, the formatting thing may come down to opinion. For me, code literals are a very strong emphasis and should be reserved to strings where the exact spelling is important, as the string may be used in a command or in code. I don't want us to overuse this format for things like github repo names, which are usually also emphasized already as hyperlinks.