[GH-ISSUE #60] proper-names should allow different formatting when a URL is used as link text #1897

New issue

Closed

opened 2026-03-07 20:02:33 +03:00 by kerem · 3 comments

kerem commented

2026-03-07 20:02:33 +03:00

Owner

Originally created by @jerryjappinen on GitHub (May 26, 2017).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/60

Given the following configuration:

{
  "proper-names": {
    "names": [
      "GitHub"
    ]
  }
}

I can write this:

Awesome things related to Vue available at GitHub

Awesome things related to Vue available at [GitHub](https://github.com/vuejs/awesome-vue)

But not any of this:

Awesome things related to Vue available at github.com

Awesome things related to Vue available at [github.com](https://github.com/vuejs/awesome-vue)
Awesome things related to Vue available at [github.com/vuejs](https://github.com/vuejs/awesome-vue)
Awesome things related to Vue available at [github.com/vuejs/awesome-vue](https://github.com/vuejs/awesome-vue/)

I also tried adding "github.com" to the configuration both before and after "GitHub" but it didn't help, I still got the error.

I believe it's obvious that the latter should also be allowed here. When linking between domains, I quite frequently prefer writing the URL for the user, but will use the link formatting to only write the relevant part and make the link more readable. I might drop the protocol, parameters, trailing slashes and such.

I think proper-names should exempt all URLs and emails. This seems to be the intention as well as the code does not trigger errors from bare URLs, but it still disallows using the URL pattern as a user-facing link text, which probably isn't what we want.

Originally created by @jerryjappinen on GitHub (May 26, 2017). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/60 Given the following configuration: ```json { "proper-names": { "names": [ "GitHub" ] } } ``` I can write this: Awesome things related to Vue available at [GitHub](https://github.com/vuejs/awesome-vue) ```md Awesome things related to Vue available at [GitHub](https://github.com/vuejs/awesome-vue) ``` But **not** any of this: Awesome things related to Vue available at [github.com](https://github.com/vuejs/awesome-vue) ```md Awesome things related to Vue available at [github.com](https://github.com/vuejs/awesome-vue) Awesome things related to Vue available at [github.com/vuejs](https://github.com/vuejs/awesome-vue) Awesome things related to Vue available at [github.com/vuejs/awesome-vue](https://github.com/vuejs/awesome-vue/) ``` I also tried adding `"github.com"` to the configuration both before and after `"GitHub"` but it didn't help, I still got the error. --- I believe it's obvious that the latter should also be allowed here. When linking between domains, I quite frequently prefer writing the URL for the user, but will use the link formatting to only write the relevant part and make the link more readable. I might drop the protocol, parameters, trailing slashes and such. I think `proper-names` should exempt all URLs and emails. This seems to be the intention as well as the code does not trigger errors from bare URLs, but it still disallows using the URL pattern as a user-facing link text, which probably isn't what we want.

kerem

2026-03-07 20:02:33 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-07 20:02:34 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 26, 2017):

Link text is usually meant to be descriptive, so I think the current behavior is a sensible default. But your scenario makes sense as well, so I would be inclined to add an option to exempt link text from this rule to enable it. Would that work?

@DavidAnson commented on GitHub (May 26, 2017): Link text is usually meant to be descriptive, so I think the current behavior is a sensible default. But your scenario makes sense as well, so I would be inclined to add an option to exempt link text from this rule to enable it. Would that work?

kerem commented

2026-03-07 20:02:35 +03:00

Author

Owner

@jerryjappinen commented on GitHub (May 29, 2017):

That would work for me yeah in this case.

However I still couldn't write "the domain name of GitHub is github.com" anywhere without getting an error, so I wonder if we could handle this in a more generic way. If I do have both "github.com" and "GitHub" in my configuration, what is the expected behavior? Does the order matter?

What I've been writing documentation for a my vue-webpack project template and I noticed that I wanted to do the following:

Vue should be written with a capital V
Vue.js should also be written with a capital V
vue.js as a file name should be written with lowercase if that's what the file is called. Not a problem since I use code blocks for file names and those are exempt, and there wouldn't be any way for the linter to tell the difference anyhow.
Vuex is the name of a separate library which should be written with a capital V. Not a problem, linter doesn't give false positives.
But vue-router is also a separate library, which should be written with a lowercase v. I get an error from the linter even if I have "vue-router" or "vue-" in my configuration in addition to "Vue". This makes sense if I think about the implementation (dash is a punctuation character), but I think it's actually a common use case (for example many plugins for ESLint have all lowercase names with the string -eslint- included) and there should be a way to handle this.

I worked around this issue by enclosing all names that look like this in code blocks, which is fine (ish) for me, but they're not all package names and the same issue comes up with other stylised names or domain names used outside of link texts.

There's probably way more complexity in here that makes sense to try to tackle with this feature of a simple linter, but anyways it's interesting to consider. Perhaps there's an easy solution here somewhere that might involve checking if a string is whitelisted in the config before the linter warns about it, whitelisting all URL patterns or something else.

@jerryjappinen commented on GitHub (May 29, 2017): That would work for me yeah in this case. However I still couldn't write "the domain name of GitHub is _github.com_" anywhere without getting an error, so I wonder if we could handle this in a more generic way. If I do have both `"github.com"` and `"GitHub"` in my configuration, what is the expected behavior? Does the order matter? What I've been writing documentation for a my [vue-webpack project template](https://eiskis.gitbooks.io/vue-webpack-docs/content/) and I noticed that I wanted to do the following: - _Vue_ should be written with a capital V - _Vue.js_ should also be written with a capital V - `vue.js` as a file name should be written with lowercase if that's what the file is called. Not a problem since I use code blocks for file names and those are exempt, and there wouldn't be any way for the linter to tell the difference anyhow. - Vuex is the name of a separate library which should be written with a capital V. Not a problem, linter doesn't give false positives. - But _vue-router_ is also a separate library, which should be written with a lowercase _v_. I get an error from the linter even if I have `"vue-router"` or `"vue-"` in my configuration in addition to `"Vue"`. This makes sense if I think about the implementation (dash is a punctuation character), but I think it's actually a common use case (for example many plugins for ESLint have all lowercase names with the string `-eslint-` included) and there should be a way to handle this. I worked around this issue by enclosing all names that look like this in code blocks, which is fine (ish) for me, but they're not all package names and the same issue comes up with other stylised names or domain names used outside of link texts. There's probably way more complexity in here that makes sense to try to tackle with this feature of a simple linter, but anyways it's interesting to consider. Perhaps there's an easy solution here somewhere that might involve checking if a string is whitelisted in the config before the linter warns about it, whitelisting all URL patterns or something else.

kerem commented

2026-03-07 20:02:35 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 29, 2017):

Interesting scenario! Order should not matter, so I don't think that will help you. I'll create a test file from your examples above and play around with it soon. Some ideas I'll explore are exempting link text and treating period/hyphen as part of the word. I'd rather not support regular expressions, but that may be something else to consider. Thanks again, please let me know if there are other tricky scenarios here!

@DavidAnson commented on GitHub (May 29, 2017): Interesting scenario! Order should not matter, so I don't think that will help you. I'll create a test file from your examples above and play around with it soon. Some ideas I'll explore are exempting link text and treating period/hyphen as part of the word. I'd rather not support regular expressions, but that may be something else to consider. Thanks again, please let me know if there are other tricky scenarios here!

kerem referenced this issue

2026-03-07 20:14:43 +03:00

[PR #1897] [MERGED] Update test repository snapshots. #3633